expecco Wiki (Version 25.x) - Benutzerbeiträge [de]

Plot/Graph Action Blocks

2026-03-03T13:37:42Z

Sv: /* Introduction */

== Introduction ==

With expecco18.1, a new block type named "''Plot/Graph Actions''" was first introduced.
These behave similar to other script action blocks, in that they are defined by a script
(in this case: gnuplot scripting language) and are placed into the test sequence flow
just like any other block.

However, when executed, these actions generate a graphic document (jpeg, png or postscript),
which is then either added to the activity log, or added as attachment. It will therefore be
available in the generated "<code>elf</code>" execution log file, or shown in the generated "<code>pdf</code>" report file.
Of course, you can do anything you like with the generated graphic file, by feeding the name
of the generated file to another action for further processing.

Notice: if you prefer other graphic packages or other programming languages, you may of course use R language scripts or Python scripts (with matplotlib and/or seaboarn) to generate graphics in a similar way.

== Creating Plot/Graph Action Blocks ==

Plot/graph action blocks are created via the
"''Actions'' - ''More'' - ''Plot/Graph''" menu item.

[[Datei:Plot_Graph_Actions_in_Menu.png|200px]]

Select the "''Plot/Graph''" item, to create a new gnuplot action.
An initial set of input pins and an initial (demo-) script is generated for you.

For details on the scripting language, please refer to the public
[http://www.gnuplot.info/docs_6.0/Gnuplot_6.pdf gnuplot documentation].

Any input pin named "<code><pinName></code>" is available in the script as "<code>%(pinName)</code>".
Thus, the script can be parametrized in arbitrary ways.
A number of pins are already created for you; these are:
* "'''outputFile'''" both an input and an output. If the input is specified, gnuplot will generate the plot into that file. Otherwise, a new temporary file will be created and the output written into that. In any case will the actual outputFileName be available on the corresponding output pin for further processing.

* "'''outputFormat'''" specifies the kind of file to generate. For inclusion into the report, an image format should be chosen (i.e. one of "jpeg", "png" or "gif"). For archival or to generate high quality documents, you can also choose "postscript" or "svg". However, those can (currently) not be automatically converted for the pdf report. On Unix systems, you can also specify "x11" as output format. In this case, a window is opened, displaying the generated graph. Be aware that expecco is (currently) not informed about the window being closed, so you may have to stop the test-run via the expecco-"Stop" button.

* "'''title'''" A title string to be drawn above the graphic (actually, the position of the title is specified by the "set key" gnuplot expression, inside the script)

* "'''data'''" If connected, and a collection of values is present, these values will be written into a temporary data file, and the filename is available in the gnuplot script as "<code>%(dataFile)</code>". This will be the raw data, to be processed by the script.

* "'''dataSize'''" There is no pin for that, but the value is available to the script. It provides the number of data points (or rows) in the data file.

* "'''attachToLog'''" if true (the default), the generated graph will be attached to the final pdf report. This pin's value is not forwarded to the gnuplot script.

You can add additional input pins and refer to the corresponding pin value in the script with the "%(...)" notation.

== A Simple Graph Script ==

A typical gnuplot script looks like:

# The code below is sent to gnuplot and the generated output
# will be stored in a file named %%(outputFile)
# (unless explicitly specified, a temporary file is created)
#
set output "%(outputFile)"

#
set term %(outputFormat)

# All input pin values can be used here as %%(nameOfPin).
# so the next line controls the title via the "title" pin
#
set title "%(title)"

# You can add more pins.
# For example, add pins named "min" and "max" with type Number,
# and replace "-10:10" below by "%%(min):%%(max) to parametrize the y-axis range.
set key left box
plot [1:%(dataSize)] [-10:10] "%(dataFile)" title "My Data" with impulses

to plot a simple impulse graph of the data values, as presented at the input pin,
assuming that the pins get the following values:
* "outputFile" - leave unconnected or remove the pin (to let the action choose a temp file)
* "outputFormat" - freeze as "<code>png</code>"
* "title" - any title - such as "Measurement #1"
* "data" - a vector of numbers

Of course, this is actually the simplest possible script to render such data.
Gnuplot provides a wide area of possible plots, both 2D and 3D, with or without colors, etc.
A few examples are provided in the "<code>Plot_Graph Library.ets</code>", but much more is found on the gnuplot
website [http://www.gnuplot.info/docs_6.0/Gnuplot_6.pdf gnu plot documentation].

== Short List of Useful Script Commands ==

For a full list, please take a look at the [http://www.gnuplot.info/docs_6.0/Gnuplot_6.pdf gnu plot documentation]. The following list is only presenting the most common plot commands:
* <code>plot [xMin:xMax] [yMin:yMax] "nameOfDataFile" title "graph title" with impulses</code> You can omit the "[yMin:yMax]" parameter, for a reasonable box to be automatically chosen by gnuplot. Replace "nameOfDataFile" by "%(dataFile)" if the data comes via an input pin and is not already in a file.

*<code>plot [xMin:xMax] [yMin:yMax] "nameOfDataFile" title "graph title"</code> Without the "impulses" parameter, a regular graph is drawn (straight lines between points)

*<code>plot [xMin:xMax] [yMin:yMax] "nameOfDataFile" title "graph title" with: lines</code> The same as above (straight lines between points)

*<code>plot [xMin:xMax] [yMin:yMax] "nameOfDataFile" title "graph title" with: dots</code> Draws dots

*<code>plot [xMin:xMax] [yMin:yMax] "nameOfDataFile" title "graph title" with candlesticks</code> the data file should contain multiple colums per line. Select the colums with a "using..." parameter.

*<code>set key left box</code> defines the position (left) and type (boxed) of the graph-title (the string comes from the <code>title "graph title"</code> argument in the plot command)

*<code>set title "someTitle"</code> defines a headline title

*<code>set term %(outputFormat)</code> defines the type of image to be generated. For "%(outputFormat)", the input pin's format is generated. Otherwise, you can also hardcode any of "<code>png</code>", "<code>jpg</code>", etc. here

A few examples are found in the demo library: "Plot_Graph_Library.ets", which is found in the plugin's folder and in the online documentation [http://www.gnuplot.info/docs_5.0/gnuplot.pdf "http://www.gnuplot.info/docs_5.0/gnuplot.pdf"].

== Accessing Data from Attachments ==

You can directly access expecco attachment files by their name inside the script. I.e. if you have an attachment with file named "<code>foo.dat</code>", use <code>... data "foo.dat" ...</code> inside the script. Notice that the attchment's filename is to be used - not its name in the tree.

== Plotting Multiple Graphs into a Single Picture ==

To do this, generate multiple datasets (as ascii files, with one textline per row). Add <code>data</code> input pins and feed them the filenames. Add multiple <code>plot</code> commands, each with its own "<code>%(data</code>)" argument, and possibly with its own graph-title.

== Changing the Size of the Generated Image ==

By default, the generated image's size is 640 x 400 pixels.
For a fix size, change the script's "<code>set term</code>" statement to:

set term %(outputFormat) size <width>,<height>

where <width> and <height> define the size in pixels.

Alternatively, add two pins named "''width''" and "''height''", and
change the statement to:

set term %(outputFormat) size %(width),%(height)

and provide the desired size (as integers) at the input pins.

== Caveats ==

Do not place <code>pause</code> statements into the script; there is no input stream given to gnuplot, so it will immediately read an EOF (end of file) and proceed.

== Complete Example 1: Gathering Response Times of MQTT Protocol Messages ==

This example demonstrates, how a test suite can gather response times of a remote system,
when sending MQTT messages to it.

==== Step 1: Define the Test Sequence ====

this is a very simple publish-response setup, in that a topic is published to an MQTT broker,
and the time measured, until the notification arrives (in order to run this on your machine,
the expecco MQTT plugin needs to be installed):

Outside (Schema) view of the measuring action:

[[Datei:Schema_Measuring_MQTT.png|400px]]

which is implemented as:

[[Datei:Net_Measuring_MQTT.png|800px]]

The yellow area does the MQTT setup. First, an MQTT client connection is created,
and the client handle forwarded to the Subscribe action, which registers expecco
to react to the "expeccoTesting/test" topic.

The green area does the actual publish operation,
publishing the "Hello from Expecco" string on this topic.

In parallel, the blue area waits for the next incoming event,
(and generates a printed detail info on the received packet for the
activity log).

The red area contains a stopWatch action block, which gets started
with when the publish is done, and stops when the event arrives.

The measurement action is prametrized with the broker's host and port,
and generates the measured timeDuration as output.

==== Step 2: Test Run ====

Assuming that you have an MQTT client running on the local host,
the test sequence can be immediately tried via the Test/Demo page:

[[Datei:Test_Measuring_MQTT.png|300px]]

A good strategy is to package the MQTT broker into a docker file.
Here is the MQTT client's output of the above run:

$ sh rundocker.sh
1522084243: mosquitto version 1.4.8 (build date Thu, 01 Mar 2018 09:34:49 -0500) starting
1522084243: Using default config.
1522084243: Opening ipv4 listen socket on port 1883.
1522084243: Opening ipv6 listen socket on port 1883.
1522084272: New connection from 172.17.0.1 on port 1883.
1522084272: New client connected from 172.17.0.1 as expeccoMQTT (c1, k0).
1522084272: Client expeccoMQTT disconnected.

and here the activitylog in expecco:

[[Datei:Log1_Measuring_MQTT.png|600px]]

with the event info detail:

[[Datei:Log2_Measuring_MQTT.png|600px]]

==== Step 3: Running that Sequence Multiple Times ====

Now that we have verified, that the communication with the MQTT broker works correctly,
we create another action bock, which runs the above action multiple times and collects
all the execution times:

[[Datei:Multiple_Measuring_MQTT.png|700px]]

[ explanation: first, a new empty colletion is created, then, the timing values of
the multi-triggered measure-step are all added to this collection.
When done (no step active), the collection is forwarded (now filled) to the output pin]

Here is the activity log after 10 runs:

[[Datei:Log1_Multiple_Measuring_MQTT.png|700px]]

==== Step 4: Adding the Graph ====

The last step is the easiest: select the "New Plot/Graph" action block from the menu,
name it "Time Measurement Graph"
and change its autogenerated gnuplot script to:

set output "%(outputFile)"
set term %(outputFormat)
set title "%(title)"
set key left box
plot [1:%(dataSize)] [0:100] "%(dataFile)" title "%(lineTitle)" with impulses

then place a step of it into your network and connect the "collectedTimes" output of the above measurement step with the "data" input
of the "Measurement-Graph" step:

[[Datei:Multiple_Measuring_plus_Graph_MQTT.png|500px]]

Running it, and generating the report, produces the following pdf-report (the logging of subactivities was disabled for this report):

[[Datei:Multiple_Measuring_MQTT_Report_img.png|700px]]

[[Datei:Multiple_Measuring_MQTT_Report.pdf]]

== Example 1 Simplified: Using Probes to Gather the Data ==

The above data collection may look a bit complicated, due to the need for start/stop synchronization.
A much nicer and easier to use solution is in using a probe to gather the data.
For this, we need a probe which does no range checks, but instead only collects the incoming values:

[[Datei:Measuring_MQTT_with_Probe.png|700px]]

Here, a probe was added (via the "timeDelta" pin's "Add Probe" menu item),
and specified to "collect incoming data without check":

[[Datei:Measuring_MQTT_with_ProbeMenu.png|500px]]

Now that we have a probe at the roundtrip time,
the outer measurement looks much simpler:

* reset the probe (to clear any previously gathered data)
* prime the probe enable data collecting)
* run the roundtrip-test n-times
* unprime the probe (disable further data collecting)
* fetch the probe's values and pass them to the gnuplot action

[[Datei:Measuring_MQTT_with_Probe2.png|500px]]

== See Also ==
[http://www.gnuplot.info/docs_6.0/Gnuplot_6.pdf Gnuplot Manual]
 [https://alvinalexander.com/technology/gnuplot-charts-graphs-examples Collection of Examples]

"[[R Action Blocks]]" which provide similar graph/plot functions in addition to sophisticated mathematical and statistics libraries.
 "[[Octave Script Action Tutorial|Octave/Matlab Actions]]" another framework for mathematical computations and/or to generate graphs/plots.



[[Category: Languages ]]

Plot/Graph Action Blocks

2026-03-03T13:36:32Z

Sv: Renamed %(data) to %(dataFile)

== Introduction ==

With expecco18.1, a new block type named "''Plot/Graph Actions''" is introduced.
These behave similar to other script action blocks, in that they are defined by a script
(in this case: gnuplot scripting language) and are placed into the test sequence flow
just like any other block.

However, when executed, these actions generate a graphic document (jpeg, png or postscript),
which is then either added to the activity log, or added as attachment. It will therefore be
available in the generated "<code>elf</code>" execution log file, or shown in the generated "<code>pdf</code>" report file.
Of course, you can do anything you like with the generated graphic file, by feeding the name
of the generated file to another action for further processing.

Notice: if you prefer other graphic packages or other programming languages, you may of course use R language scripts or Python scripts (with matplotlib and/or seaboarn) to generate graphics in a similar way.

== Creating Plot/Graph Action Blocks ==

Plot/graph action blocks are created via the
"''Actions'' - ''More'' - ''Plot/Graph''" menu item.

[[Datei:Plot_Graph_Actions_in_Menu.png|200px]]

Select the "''Plot/Graph''" item, to create a new gnuplot action.
An initial set of input pins and an initial (demo-) script is generated for you.

For details on the scripting language, please refer to the public
[http://www.gnuplot.info/docs_6.0/Gnuplot_6.pdf gnuplot documentation].

Any input pin named "<code><pinName></code>" is available in the script as "<code>%(pinName)</code>".
Thus, the script can be parametrized in arbitrary ways.
A number of pins are already created for you; these are:
* "'''outputFile'''" both an input and an output. If the input is specified, gnuplot will generate the plot into that file. Otherwise, a new temporary file will be created and the output written into that. In any case will the actual outputFileName be available on the corresponding output pin for further processing.

* "'''outputFormat'''" specifies the kind of file to generate. For inclusion into the report, an image format should be chosen (i.e. one of "jpeg", "png" or "gif"). For archival or to generate high quality documents, you can also choose "postscript" or "svg". However, those can (currently) not be automatically converted for the pdf report. On Unix systems, you can also specify "x11" as output format. In this case, a window is opened, displaying the generated graph. Be aware that expecco is (currently) not informed about the window being closed, so you may have to stop the test-run via the expecco-"Stop" button.

* "'''title'''" A title string to be drawn above the graphic (actually, the position of the title is specified by the "set key" gnuplot expression, inside the script)

* "'''data'''" If connected, and a collection of values is present, these values will be written into a temporary data file, and the filename is available in the gnuplot script as "<code>%(dataFile)</code>". This will be the raw data, to be processed by the script.

* "'''dataSize'''" There is no pin for that, but the value is available to the script. It provides the number of data points (or rows) in the data file.

* "'''attachToLog'''" if true (the default), the generated graph will be attached to the final pdf report. This pin's value is not forwarded to the gnuplot script.

You can add additional input pins and refer to the corresponding pin value in the script with the "%(...)" notation.

== A Simple Graph Script ==

A typical gnuplot script looks like:

# The code below is sent to gnuplot and the generated output
# will be stored in a file named %%(outputFile)
# (unless explicitly specified, a temporary file is created)
#
set output "%(outputFile)"

#
set term %(outputFormat)

# All input pin values can be used here as %%(nameOfPin).
# so the next line controls the title via the "title" pin
#
set title "%(title)"

# You can add more pins.
# For example, add pins named "min" and "max" with type Number,
# and replace "-10:10" below by "%%(min):%%(max) to parametrize the y-axis range.
set key left box
plot [1:%(dataSize)] [-10:10] "%(dataFile)" title "My Data" with impulses

to plot a simple impulse graph of the data values, as presented at the input pin,
assuming that the pins get the following values:
* "outputFile" - leave unconnected or remove the pin (to let the action choose a temp file)
* "outputFormat" - freeze as "<code>png</code>"
* "title" - any title - such as "Measurement #1"
* "data" - a vector of numbers

Of course, this is actually the simplest possible script to render such data.
Gnuplot provides a wide area of possible plots, both 2D and 3D, with or without colors, etc.
A few examples are provided in the "<code>Plot_Graph Library.ets</code>", but much more is found on the gnuplot
website [http://www.gnuplot.info/docs_6.0/Gnuplot_6.pdf gnu plot documentation].

== Short List of Useful Script Commands ==

For a full list, please take a look at the [http://www.gnuplot.info/docs_6.0/Gnuplot_6.pdf gnu plot documentation]. The following list is only presenting the most common plot commands:
* <code>plot [xMin:xMax] [yMin:yMax] "nameOfDataFile" title "graph title" with impulses</code> You can omit the "[yMin:yMax]" parameter, for a reasonable box to be automatically chosen by gnuplot. Replace "nameOfDataFile" by "%(dataFile)" if the data comes via an input pin and is not already in a file.

*<code>plot [xMin:xMax] [yMin:yMax] "nameOfDataFile" title "graph title"</code> Without the "impulses" parameter, a regular graph is drawn (straight lines between points)

*<code>plot [xMin:xMax] [yMin:yMax] "nameOfDataFile" title "graph title" with: lines</code> The same as above (straight lines between points)

*<code>plot [xMin:xMax] [yMin:yMax] "nameOfDataFile" title "graph title" with: dots</code> Draws dots

*<code>plot [xMin:xMax] [yMin:yMax] "nameOfDataFile" title "graph title" with candlesticks</code> the data file should contain multiple colums per line. Select the colums with a "using..." parameter.

*<code>set key left box</code> defines the position (left) and type (boxed) of the graph-title (the string comes from the <code>title "graph title"</code> argument in the plot command)

*<code>set title "someTitle"</code> defines a headline title

*<code>set term %(outputFormat)</code> defines the type of image to be generated. For "%(outputFormat)", the input pin's format is generated. Otherwise, you can also hardcode any of "<code>png</code>", "<code>jpg</code>", etc. here

A few examples are found in the demo library: "Plot_Graph_Library.ets", which is found in the plugin's folder and in the online documentation [http://www.gnuplot.info/docs_5.0/gnuplot.pdf "http://www.gnuplot.info/docs_5.0/gnuplot.pdf"].

== Accessing Data from Attachments ==

You can directly access expecco attachment files by their name inside the script. I.e. if you have an attachment with file named "<code>foo.dat</code>", use <code>... data "foo.dat" ...</code> inside the script. Notice that the attchment's filename is to be used - not its name in the tree.

== Plotting Multiple Graphs into a Single Picture ==

To do this, generate multiple datasets (as ascii files, with one textline per row). Add <code>data</code> input pins and feed them the filenames. Add multiple <code>plot</code> commands, each with its own "<code>%(data</code>)" argument, and possibly with its own graph-title.

== Changing the Size of the Generated Image ==

By default, the generated image's size is 640 x 400 pixels.
For a fix size, change the script's "<code>set term</code>" statement to:

set term %(outputFormat) size <width>,<height>

where <width> and <height> define the size in pixels.

Alternatively, add two pins named "''width''" and "''height''", and
change the statement to:

set term %(outputFormat) size %(width),%(height)

and provide the desired size (as integers) at the input pins.

== Caveats ==

Do not place <code>pause</code> statements into the script; there is no input stream given to gnuplot, so it will immediately read an EOF (end of file) and proceed.

== Complete Example 1: Gathering Response Times of MQTT Protocol Messages ==

This example demonstrates, how a test suite can gather response times of a remote system,
when sending MQTT messages to it.

==== Step 1: Define the Test Sequence ====

this is a very simple publish-response setup, in that a topic is published to an MQTT broker,
and the time measured, until the notification arrives (in order to run this on your machine,
the expecco MQTT plugin needs to be installed):

Outside (Schema) view of the measuring action:

[[Datei:Schema_Measuring_MQTT.png|400px]]

which is implemented as:

[[Datei:Net_Measuring_MQTT.png|800px]]

The yellow area does the MQTT setup. First, an MQTT client connection is created,
and the client handle forwarded to the Subscribe action, which registers expecco
to react to the "expeccoTesting/test" topic.

The green area does the actual publish operation,
publishing the "Hello from Expecco" string on this topic.

In parallel, the blue area waits for the next incoming event,
(and generates a printed detail info on the received packet for the
activity log).

The red area contains a stopWatch action block, which gets started
with when the publish is done, and stops when the event arrives.

The measurement action is prametrized with the broker's host and port,
and generates the measured timeDuration as output.

==== Step 2: Test Run ====

Assuming that you have an MQTT client running on the local host,
the test sequence can be immediately tried via the Test/Demo page:

[[Datei:Test_Measuring_MQTT.png|300px]]

A good strategy is to package the MQTT broker into a docker file.
Here is the MQTT client's output of the above run:

$ sh rundocker.sh
1522084243: mosquitto version 1.4.8 (build date Thu, 01 Mar 2018 09:34:49 -0500) starting
1522084243: Using default config.
1522084243: Opening ipv4 listen socket on port 1883.
1522084243: Opening ipv6 listen socket on port 1883.
1522084272: New connection from 172.17.0.1 on port 1883.
1522084272: New client connected from 172.17.0.1 as expeccoMQTT (c1, k0).
1522084272: Client expeccoMQTT disconnected.

and here the activitylog in expecco:

[[Datei:Log1_Measuring_MQTT.png|600px]]

with the event info detail:

[[Datei:Log2_Measuring_MQTT.png|600px]]

==== Step 3: Running that Sequence Multiple Times ====

Now that we have verified, that the communication with the MQTT broker works correctly,
we create another action bock, which runs the above action multiple times and collects
all the execution times:

[[Datei:Multiple_Measuring_MQTT.png|700px]]

[ explanation: first, a new empty colletion is created, then, the timing values of
the multi-triggered measure-step are all added to this collection.
When done (no step active), the collection is forwarded (now filled) to the output pin]

Here is the activity log after 10 runs:

[[Datei:Log1_Multiple_Measuring_MQTT.png|700px]]

==== Step 4: Adding the Graph ====

The last step is the easiest: select the "New Plot/Graph" action block from the menu,
name it "Time Measurement Graph"
and change its autogenerated gnuplot script to:

set output "%(outputFile)"
set term %(outputFormat)
set title "%(title)"
set key left box
plot [1:%(dataSize)] [0:100] "%(dataFile)" title "%(lineTitle)" with impulses

then place a step of it into your network and connect the "collectedTimes" output of the above measurement step with the "data" input
of the "Measurement-Graph" step:

[[Datei:Multiple_Measuring_plus_Graph_MQTT.png|500px]]

Running it, and generating the report, produces the following pdf-report (the logging of subactivities was disabled for this report):

[[Datei:Multiple_Measuring_MQTT_Report_img.png|700px]]

[[Datei:Multiple_Measuring_MQTT_Report.pdf]]

== Example 1 Simplified: Using Probes to Gather the Data ==

The above data collection may look a bit complicated, due to the need for start/stop synchronization.
A much nicer and easier to use solution is in using a probe to gather the data.
For this, we need a probe which does no range checks, but instead only collects the incoming values:

[[Datei:Measuring_MQTT_with_Probe.png|700px]]

Here, a probe was added (via the "timeDelta" pin's "Add Probe" menu item),
and specified to "collect incoming data without check":

[[Datei:Measuring_MQTT_with_ProbeMenu.png|500px]]

Now that we have a probe at the roundtrip time,
the outer measurement looks much simpler:

* reset the probe (to clear any previously gathered data)
* prime the probe enable data collecting)
* run the roundtrip-test n-times
* unprime the probe (disable further data collecting)
* fetch the probe's values and pass them to the gnuplot action

[[Datei:Measuring_MQTT_with_Probe2.png|500px]]

== See Also ==
[http://www.gnuplot.info/docs_6.0/Gnuplot_6.pdf Gnuplot Manual]
 [https://alvinalexander.com/technology/gnuplot-charts-graphs-examples Collection of Examples]

"[[R Action Blocks]]" which provide similar graph/plot functions in addition to sophisticated mathematical and statistics libraries.
 "[[Octave Script Action Tutorial|Octave/Matlab Actions]]" another framework for mathematical computations and/or to generate graphs/plots.



[[Category: Languages ]]

Plot/Graph Action Blocks

2026-03-03T11:14:53Z

Sv: /* Creating Plot/Graph Action Blocks */

== Introduction ==

With expecco18.1, a new block type named "''Plot/Graph Actions''" is introduced.
These behave similar to other script action blocks, in that they are defined by a script
(in this case: gnuplot scripting language) and are placed into the test sequence flow
just like any other block.

However, when executed, these actions generate a graphic document (jpeg, png or postscript),
which is then either added to the activity log, or added as attachment. It will therefore be
available in the generated "<code>elf</code>" execution log file, or shown in the generated "<code>pdf</code>" report file.
Of course, you can do anything you like with the generated graphic file, by feeding the name
of the generated file to another action for further processing.

Notice: if you prefer other graphic packages or other programming languages, you may of course use R language scripts or Python scripts (with matplotlib and/or seaboarn) to generate graphics in a similar way.

== Creating Plot/Graph Action Blocks ==

Plot/graph action blocks are created via the
"''Actions'' - ''More'' - ''Plot/Graph''" menu item.

[[Datei:Plot_Graph_Actions_in_Menu.png|200px]]

Select the "''Plot/Graph''" item, to create a new gnuplot action.
An initial set of input pins and an initial (demo-) script is generated for you.

For details on the scripting language, please refer to the public gnuplot documentation
[http://www.gnuplot.info/docs_6.0/Gnuplot_6.pdf "http://www.gnuplot.info/docs_6.0/Gnuplot_6.pdf"].

Any input pin named "<code><pinName></code>" is available in the script as "<code>%(pinName)</code>".
Thus, the script can be parametrized in arbitrary ways.
A number of pins are already created for you; these are:
* "'''outputFile'''" both an input and an output. If the input is specified, gnuplot will generate the plot into that file. Otherwise, a new temporary file will be created and the output written into that. In any case will the actual outputFileName be available on the corresponding output pin for further processing.

* "'''outputFormat'''" specifies the kind of file to generate. For inclusion into the report, an image format should be chosen (i.e. one of "jpeg", "png" or "gif"). For archival or to generate high quality documents, you can also choose "postscript" or "svg". However, those can (currently) not be automatically converted for the pdf report. On Unix systems, you can also specify "x11" as output format. In this case, a window is opened, displaying the generated graph. Be aware that expecco is (currently) not informed about the window being closed, so you may have to stop the test-run via the expecco-"Stop" button.

* "'''title'''" A title string to be drawn above the graphic (actually, the position of the title is specified by the "set key" gnuplot expression, inside the script)

* "'''data'''" If connected, and a collection of values is present, these values will be written into a temporary data file, and the filename is available in the gnuplot script as "<code>%(data)</code>". Theis will be the raw data, to be processed by the script.

* "'''dataSize'''" There is no pin for that, but the value is available to the script. It provides the number of data points (or rows) in the data file.

* "'''attachToLog'''" if true (the default), the generated graph will be attached to the final pdf report. This pin's value is not forwarded to the gnuplot script.

You can add additional input pins and refer to the corresponding pin value in the script with the "%(...)" notation.

== A Simple Graph Script ==

A typical gnuplot script looks like:

# The code below is sent to gnuplot and the generated output
# will be stored in a file named %%(outputFile)
# (unless explicitly specified, a temporary file is created)
#
set output "%(outputFile)"

#
set term %(outputFormat)

# All input pin values can be used here as %%(nameOfPin).
# so the next line controls the title via the "title" pin
#
set title "%(title)"

# You can add more pins.
# For example, add pins named "min" and "max" with type Number,
# and replace "-10:10" below by "%%(min):%%(max) to parametrize the y-axis range.
set key left box
plot [1:%(dataSize)] [-10:10] "%(data)" title "My Data" with impulses

to plot a simple impulse graph of the data values, as presented at the input pin,
assuming that the pins get the following values:
* "outputFile" - leave unconnected or remove the pin (to let the action choose a temp file)
* "outputFormat" - freeze as "<code>png</code>"
* "title" - any title - such as "Measurement #1"
* "data" - a vector of numbers

Of course, this is actually the simplest possible script to render such data.
Gnuplot provides a wide area of possible plots, both 2D and 3D, with or without colors, etc.
A few examples are provided in the "<code>Plot_Graph Library.ets</code>", but much more is found on the gnuplot
website and gnuplot documentation [http://www.gnuplot.info/docs_5.0/gnuplot.pdf "http://www.gnuplot.info/docs_5.0/gnuplot.pdf"].

== Short List of Useful Script Commands ==

For a full list, please take a look at the gnu plot documentation [http://www.gnuplot.info/docs_5.0/gnuplot.pdf "http://www.gnuplot.info/docs_5.0/gnuplot.pdf"]. The following list is only presenting the most common plot commands:
* <code>plot [xMin:xMax] [yMin:yMax] "nameOfDataFile" title "graph title" with impulses</code> You can omit the "[yMin:yMax]" parameter, for a reasonable box to be automatically chosen by gnuplot. Replace "nameOfDataFile" by "%(data)" if the data comes via an input pin and is not already in a file.

*<code>plot [xMin:xMax] [yMin:yMax] "nameOfDataFile" title "graph title"</code> Without the "impulses" parameter, a regular graph is drawn (straight lines between points)

*<code>plot [xMin:xMax] [yMin:yMax] "nameOfDataFile" title "graph title" with: lines</code> The same as above (straight lines between points)

*<code>plot [xMin:xMax] [yMin:yMax] "nameOfDataFile" title "graph title" with: dots</code> Draws dots

*<code>plot [xMin:xMax] [yMin:yMax] "nameOfDataFile" title "graph title" with candlesticks</code> the data file should contain multiple colums per line. Select the colums with a "using..." parameter.

*<code>set key left box</code> defines the position (left) and type (boxed) of the graph-title (the string comes from the <code>title "graph title"</code> argument in the plot command)

*<code>set title "someTitle"</code> defines a headline title

*<code>set term %(outputFormat)</code> defines the type of image to be generated. For "%(outputFormat)", the input pin's format is generated. Otherwise, you can also hardcode any of "<code>png</code>", "<code>jpg</code>", etc. here

A few examples are found in the demo library: "Plot_Graph_Library.ets", which is found in the plugin's folder and in the online documentation [http://www.gnuplot.info/docs_5.0/gnuplot.pdf "http://www.gnuplot.info/docs_5.0/gnuplot.pdf"].

== Accessing Data from Attachments ==

You can directly access expecco attachment files by their name inside the script. I.e. if you have an attachment with file named "<code>foo.dat</code>", use <code>... data "foo.dat" ...</code> inside the script. Notice that the attchment's filename is to be used - not its name in the tree.

== Plotting Multiple Graphs into a Single Picture ==

To do this, generate multiple datasets (as ascii files, with one textline per row). Add <code>data</code> input pins and feed them the filenames. Add multiple <code>plot</code> commands, each with its own "<code>%(data</code>)" argument, and possibly with its own graph-title.

== Changing the Size of the Generated Image ==

By default, the generated image's size is 640 x 400 pixels.
For a fix size, change the script's "<code>set term</code>" statement to:

set term %(outputFormat) size <width>,<height>

where <width> and <height> define the size in pixels.

Alternatively, add two pins named "''width''" and "''height''", and
change the statement to:

set term %(outputFormat) size %(width),%(height)

and provide the desired size (as integers) at the input pins.

== Caveats ==

Do not place <code>pause</code> statements into the script; there is no input stream given to gnuplot, so it will immediately read an EOF (end of file) and proceed.

== Complete Example 1: Gathering Response Times of MQTT Protocol Messages ==

This example demonstrates, how a test suite can gather response times of a remote system,
when sending MQTT messages to it.

==== Step 1: Define the Test Sequence ====

this is a very simple publish-response setup, in that a topic is published to an MQTT broker,
and the time measured, until the notification arrives (in order to run this on your machine,
the expecco MQTT plugin needs to be installed):

Outside (Schema) view of the measuring action:

[[Datei:Schema_Measuring_MQTT.png|400px]]

which is implemented as:

[[Datei:Net_Measuring_MQTT.png|800px]]

The yellow area does the MQTT setup. First, an MQTT client connection is created,
and the client handle forwarded to the Subscribe action, which registers expecco
to react to the "expeccoTesting/test" topic.

The green area does the actual publish operation,
publishing the "Hello from Expecco" string on this topic.

In parallel, the blue area waits for the next incoming event,
(and generates a printed detail info on the received packet for the
activity log).

The red area contains a stopWatch action block, which gets started
with when the publish is done, and stops when the event arrives.

The measurement action is prametrized with the broker's host and port,
and generates the measured timeDuration as output.

==== Step 2: Test Run ====

Assuming that you have an MQTT client running on the local host,
the test sequence can be immediately tried via the Test/Demo page:

[[Datei:Test_Measuring_MQTT.png|300px]]

A good strategy is to package the MQTT broker into a docker file.
Here is the MQTT client's output of the above run:

$ sh rundocker.sh
1522084243: mosquitto version 1.4.8 (build date Thu, 01 Mar 2018 09:34:49 -0500) starting
1522084243: Using default config.
1522084243: Opening ipv4 listen socket on port 1883.
1522084243: Opening ipv6 listen socket on port 1883.
1522084272: New connection from 172.17.0.1 on port 1883.
1522084272: New client connected from 172.17.0.1 as expeccoMQTT (c1, k0).
1522084272: Client expeccoMQTT disconnected.

and here the activitylog in expecco:

[[Datei:Log1_Measuring_MQTT.png|600px]]

with the event info detail:

[[Datei:Log2_Measuring_MQTT.png|600px]]

==== Step 3: Running that Sequence Multiple Times ====

Now that we have verified, that the communication with the MQTT broker works correctly,
we create another action bock, which runs the above action multiple times and collects
all the execution times:

[[Datei:Multiple_Measuring_MQTT.png|700px]]

[ explanation: first, a new empty colletion is created, then, the timing values of
the multi-triggered measure-step are all added to this collection.
When done (no step active), the collection is forwarded (now filled) to the output pin]

Here is the activity log after 10 runs:

[[Datei:Log1_Multiple_Measuring_MQTT.png|700px]]

==== Step 4: Adding the Graph ====

The last step is the easiest: select the "New Plot/Graph" action block from the menu,
name it "Time Measurement Graph"
and change its autogenerated gnuplot script to:

set output "%(outputFile)"
set term %(outputFormat)
set title "%(title)"
set key left box
plot [1:%(dataSize)] [0:100] "%(data)" title "%(lineTitle)" with impulses

then place a step of it into your network and connect the "collectedTimes" output of the above measurement step with the "data" input
of the "Measurement-Graph" step:

[[Datei:Multiple_Measuring_plus_Graph_MQTT.png|500px]]

Running it, and generating the report, produces the following pdf-report (the logging of subactivities was disabled for this report):

[[Datei:Multiple_Measuring_MQTT_Report_img.png|700px]]

[[Datei:Multiple_Measuring_MQTT_Report.pdf]]

== Example 1 Simplified: Using Probes to Gather the Data ==

The above data collection may look a bit complicated, due to the need for start/stop synchronization.
A much nicer and easier to use solution is in using a probe to gather the data.
For this, we need a probe which does no range checks, but instead only collects the incoming values:

[[Datei:Measuring_MQTT_with_Probe.png|700px]]

Here, a probe was added (via the "timeDelta" pin's "Add Probe" menu item),
and specified to "collect incoming data without check":

[[Datei:Measuring_MQTT_with_ProbeMenu.png|500px]]

Now that we have a probe at the roundtrip time,
the outer measurement looks much simpler:

* reset the probe (to clear any previously gathered data)
* prime the probe enable data collecting)
* run the roundtrip-test n-times
* unprime the probe (disable further data collecting)
* fetch the probe's values and pass them to the gnuplot action

[[Datei:Measuring_MQTT_with_Probe2.png|500px]]

== See Also ==
[http://www.gnuplot.info/docs_5.0/gnuplot.pdf Gnuplot Manual]
 [https://alvinalexander.com/technology/gnuplot-charts-graphs-examples Collection of Examples]

"[[R Action Blocks]]" which provide similar graph/plot functions in addition to sophisticated mathematical and statistics libraries.
 "[[Octave Script Action Tutorial|Octave/Matlab Actions]]" another framework for mathematical computations and/or to generate graphs/plots.



[[Category: Languages ]]

Plot/Graph Action Blocks

2026-03-03T11:13:55Z

Sv:

== Introduction ==

With expecco18.1, a new block type named "''Plot/Graph Actions''" is introduced.
These behave similar to other script action blocks, in that they are defined by a script
(in this case: gnuplot scripting language) and are placed into the test sequence flow
just like any other block.

However, when executed, these actions generate a graphic document (jpeg, png or postscript),
which is then either added to the activity log, or added as attachment. It will therefore be
available in the generated "<code>elf</code>" execution log file, or shown in the generated "<code>pdf</code>" report file.
Of course, you can do anything you like with the generated graphic file, by feeding the name
of the generated file to another action for further processing.

Notice: if you prefer other graphic packages or other programming languages, you may of course use R language scripts or Python scripts (with matplotlib and/or seaboarn) to generate graphics in a similar way.

== Creating Plot/Graph Action Blocks ==

Plot/graph action blocks are created via the
"''Actions'' - ''More'' - ''Plot/Graph''" menu item.

[[Datei:Plot_Graph_Actions_in_Menu.png|200px]]

Select the "''Plot/Graph''" item, to create a new gnuplot action.
An initial set of input pins and an initial (demo-) script is generated for you.

For details on the scripting language, please refer to the public gnuplot documentation
[http://www.gnuplot.info/docs_5.0/gnuplot.pdf "http://www.gnuplot.info/docs_6.0/Gnuplot_6.pdf"].

Any input pin named "<code><pinName></code>" is available in the script as "<code>%(pinName)</code>".
Thus, the script can be parametrized in arbitrary ways.
A number of pins are already created for you; these are:
* "'''outputFile'''" both an input and an output. If the input is specified, gnuplot will generate the plot into that file. Otherwise, a new temporary file will be created and the output written into that. In any case will the actual outputFileName be available on the corresponding output pin for further processing.

* "'''outputFormat'''" specifies the kind of file to generate. For inclusion into the report, an image format should be chosen (i.e. one of "jpeg", "png" or "gif"). For archival or to generate high quality documents, you can also choose "postscript" or "svg". However, those can (currently) not be automatically converted for the pdf report. On Unix systems, you can also specify "x11" as output format. In this case, a window is opened, displaying the generated graph. Be aware that expecco is (currently) not informed about the window being closed, so you may have to stop the test-run via the expecco-"Stop" button.

* "'''title'''" A title string to be drawn above the graphic (actually, the position of the title is specified by the "set key" gnuplot expression, inside the script)

* "'''data'''" If connected, and a collection of values is present, these values will be written into a temporary data file, and the filename is available in the gnuplot script as "<code>%(data)</code>". Theis will be the raw data, to be processed by the script.

* "'''dataSize'''" There is no pin for that, but the value is available to the script. It provides the number of data points (or rows) in the data file.

* "'''attachToLog'''" if true (the default), the generated graph will be attached to the final pdf report. This pin's value is not forwarded to the gnuplot script.

You can add additional input pins and refer to the corresponding pin value in the script with the "%(...)" notation.

== A Simple Graph Script ==

A typical gnuplot script looks like:

# The code below is sent to gnuplot and the generated output
# will be stored in a file named %%(outputFile)
# (unless explicitly specified, a temporary file is created)
#
set output "%(outputFile)"

#
set term %(outputFormat)

# All input pin values can be used here as %%(nameOfPin).
# so the next line controls the title via the "title" pin
#
set title "%(title)"

# You can add more pins.
# For example, add pins named "min" and "max" with type Number,
# and replace "-10:10" below by "%%(min):%%(max) to parametrize the y-axis range.
set key left box
plot [1:%(dataSize)] [-10:10] "%(data)" title "My Data" with impulses

to plot a simple impulse graph of the data values, as presented at the input pin,
assuming that the pins get the following values:
* "outputFile" - leave unconnected or remove the pin (to let the action choose a temp file)
* "outputFormat" - freeze as "<code>png</code>"
* "title" - any title - such as "Measurement #1"
* "data" - a vector of numbers

Of course, this is actually the simplest possible script to render such data.
Gnuplot provides a wide area of possible plots, both 2D and 3D, with or without colors, etc.
A few examples are provided in the "<code>Plot_Graph Library.ets</code>", but much more is found on the gnuplot
website and gnuplot documentation [http://www.gnuplot.info/docs_5.0/gnuplot.pdf "http://www.gnuplot.info/docs_5.0/gnuplot.pdf"].

== Short List of Useful Script Commands ==

For a full list, please take a look at the gnu plot documentation [http://www.gnuplot.info/docs_5.0/gnuplot.pdf "http://www.gnuplot.info/docs_5.0/gnuplot.pdf"]. The following list is only presenting the most common plot commands:
* <code>plot [xMin:xMax] [yMin:yMax] "nameOfDataFile" title "graph title" with impulses</code> You can omit the "[yMin:yMax]" parameter, for a reasonable box to be automatically chosen by gnuplot. Replace "nameOfDataFile" by "%(data)" if the data comes via an input pin and is not already in a file.

*<code>plot [xMin:xMax] [yMin:yMax] "nameOfDataFile" title "graph title"</code> Without the "impulses" parameter, a regular graph is drawn (straight lines between points)

*<code>plot [xMin:xMax] [yMin:yMax] "nameOfDataFile" title "graph title" with: lines</code> The same as above (straight lines between points)

*<code>plot [xMin:xMax] [yMin:yMax] "nameOfDataFile" title "graph title" with: dots</code> Draws dots

*<code>plot [xMin:xMax] [yMin:yMax] "nameOfDataFile" title "graph title" with candlesticks</code> the data file should contain multiple colums per line. Select the colums with a "using..." parameter.

*<code>set key left box</code> defines the position (left) and type (boxed) of the graph-title (the string comes from the <code>title "graph title"</code> argument in the plot command)

*<code>set title "someTitle"</code> defines a headline title

*<code>set term %(outputFormat)</code> defines the type of image to be generated. For "%(outputFormat)", the input pin's format is generated. Otherwise, you can also hardcode any of "<code>png</code>", "<code>jpg</code>", etc. here

A few examples are found in the demo library: "Plot_Graph_Library.ets", which is found in the plugin's folder and in the online documentation [http://www.gnuplot.info/docs_5.0/gnuplot.pdf "http://www.gnuplot.info/docs_5.0/gnuplot.pdf"].

== Accessing Data from Attachments ==

You can directly access expecco attachment files by their name inside the script. I.e. if you have an attachment with file named "<code>foo.dat</code>", use <code>... data "foo.dat" ...</code> inside the script. Notice that the attchment's filename is to be used - not its name in the tree.

== Plotting Multiple Graphs into a Single Picture ==

To do this, generate multiple datasets (as ascii files, with one textline per row). Add <code>data</code> input pins and feed them the filenames. Add multiple <code>plot</code> commands, each with its own "<code>%(data</code>)" argument, and possibly with its own graph-title.

== Changing the Size of the Generated Image ==

By default, the generated image's size is 640 x 400 pixels.
For a fix size, change the script's "<code>set term</code>" statement to:

set term %(outputFormat) size <width>,<height>

where <width> and <height> define the size in pixels.

Alternatively, add two pins named "''width''" and "''height''", and
change the statement to:

set term %(outputFormat) size %(width),%(height)

and provide the desired size (as integers) at the input pins.

== Caveats ==

Do not place <code>pause</code> statements into the script; there is no input stream given to gnuplot, so it will immediately read an EOF (end of file) and proceed.

== Complete Example 1: Gathering Response Times of MQTT Protocol Messages ==

This example demonstrates, how a test suite can gather response times of a remote system,
when sending MQTT messages to it.

==== Step 1: Define the Test Sequence ====

this is a very simple publish-response setup, in that a topic is published to an MQTT broker,
and the time measured, until the notification arrives (in order to run this on your machine,
the expecco MQTT plugin needs to be installed):

Outside (Schema) view of the measuring action:

[[Datei:Schema_Measuring_MQTT.png|400px]]

which is implemented as:

[[Datei:Net_Measuring_MQTT.png|800px]]

The yellow area does the MQTT setup. First, an MQTT client connection is created,
and the client handle forwarded to the Subscribe action, which registers expecco
to react to the "expeccoTesting/test" topic.

The green area does the actual publish operation,
publishing the "Hello from Expecco" string on this topic.

In parallel, the blue area waits for the next incoming event,
(and generates a printed detail info on the received packet for the
activity log).

The red area contains a stopWatch action block, which gets started
with when the publish is done, and stops when the event arrives.

The measurement action is prametrized with the broker's host and port,
and generates the measured timeDuration as output.

==== Step 2: Test Run ====

Assuming that you have an MQTT client running on the local host,
the test sequence can be immediately tried via the Test/Demo page:

[[Datei:Test_Measuring_MQTT.png|300px]]

A good strategy is to package the MQTT broker into a docker file.
Here is the MQTT client's output of the above run:

$ sh rundocker.sh
1522084243: mosquitto version 1.4.8 (build date Thu, 01 Mar 2018 09:34:49 -0500) starting
1522084243: Using default config.
1522084243: Opening ipv4 listen socket on port 1883.
1522084243: Opening ipv6 listen socket on port 1883.
1522084272: New connection from 172.17.0.1 on port 1883.
1522084272: New client connected from 172.17.0.1 as expeccoMQTT (c1, k0).
1522084272: Client expeccoMQTT disconnected.

and here the activitylog in expecco:

[[Datei:Log1_Measuring_MQTT.png|600px]]

with the event info detail:

[[Datei:Log2_Measuring_MQTT.png|600px]]

==== Step 3: Running that Sequence Multiple Times ====

Now that we have verified, that the communication with the MQTT broker works correctly,
we create another action bock, which runs the above action multiple times and collects
all the execution times:

[[Datei:Multiple_Measuring_MQTT.png|700px]]

[ explanation: first, a new empty colletion is created, then, the timing values of
the multi-triggered measure-step are all added to this collection.
When done (no step active), the collection is forwarded (now filled) to the output pin]

Here is the activity log after 10 runs:

[[Datei:Log1_Multiple_Measuring_MQTT.png|700px]]

==== Step 4: Adding the Graph ====

The last step is the easiest: select the "New Plot/Graph" action block from the menu,
name it "Time Measurement Graph"
and change its autogenerated gnuplot script to:

set output "%(outputFile)"
set term %(outputFormat)
set title "%(title)"
set key left box
plot [1:%(dataSize)] [0:100] "%(data)" title "%(lineTitle)" with impulses

then place a step of it into your network and connect the "collectedTimes" output of the above measurement step with the "data" input
of the "Measurement-Graph" step:

[[Datei:Multiple_Measuring_plus_Graph_MQTT.png|500px]]

Running it, and generating the report, produces the following pdf-report (the logging of subactivities was disabled for this report):

[[Datei:Multiple_Measuring_MQTT_Report_img.png|700px]]

[[Datei:Multiple_Measuring_MQTT_Report.pdf]]

== Example 1 Simplified: Using Probes to Gather the Data ==

The above data collection may look a bit complicated, due to the need for start/stop synchronization.
A much nicer and easier to use solution is in using a probe to gather the data.
For this, we need a probe which does no range checks, but instead only collects the incoming values:

[[Datei:Measuring_MQTT_with_Probe.png|700px]]

Here, a probe was added (via the "timeDelta" pin's "Add Probe" menu item),
and specified to "collect incoming data without check":

[[Datei:Measuring_MQTT_with_ProbeMenu.png|500px]]

Now that we have a probe at the roundtrip time,
the outer measurement looks much simpler:

* reset the probe (to clear any previously gathered data)
* prime the probe enable data collecting)
* run the roundtrip-test n-times
* unprime the probe (disable further data collecting)
* fetch the probe's values and pass them to the gnuplot action

[[Datei:Measuring_MQTT_with_Probe2.png|500px]]

== See Also ==
[http://www.gnuplot.info/docs_5.0/gnuplot.pdf Gnuplot Manual]
 [https://alvinalexander.com/technology/gnuplot-charts-graphs-examples Collection of Examples]

"[[R Action Blocks]]" which provide similar graph/plot functions in addition to sophisticated mathematical and statistics libraries.
 "[[Octave Script Action Tutorial|Octave/Matlab Actions]]" another framework for mathematical computations and/or to generate graphs/plots.



[[Category: Languages ]]

Release Notes 26.x

2026-02-23T13:31:04Z

Sv: /* Release 26.1 (Q2 2026) */

See also: [[Release Notes 25.x]]
 

== Release 26.2 (Q4 2026) ==

== Release 26.1 (Q2 2026) ==
*Feature: Qt-Plugin supports Qt6.8 ([[QT_Testing/en#ExpeccoTestService_Library%3A_Delivery_in_Expecco_Versions|Delivered versions for QT and build environment]])
* Feature: improved search text box behavior in text editors (type RETURN, CMD-f or CMD-b while box is open) and back to original position button added.

Release Notes 26.x

2026-02-23T13:30:43Z

Sv: Release dates added

See also: [[Release Notes 25.x]]
 

== Release 26.2 (Q4 2026) ==

== Release 26.1 (Q" 2026) ==
*Feature: Qt-Plugin supports Qt6.8 ([[QT_Testing/en#ExpeccoTestService_Library%3A_Delivery_in_Expecco_Versions|Delivered versions for QT and build environment]])
* Feature: improved search text box behavior in text editors (type RETURN, CMD-f or CMD-b while box is open) and back to original position button added.

Hauptseite

2026-02-23T13:29:46Z

Sv:

[[Hauptseite/en|English Version]]

Klicken Sie links auf ''"Letzte Änderungen"'' ("Recent changes") um die neuesten Einträge in der Dokumentation zu sehen. Sie sehen dann meist, woran unsere Entwickler gerade vornehmlich arbeiten.

<h2>expecco</h2>

<div style="display:flex; flex-wrap:wrap; padding:0; white-space:nowrap">
<div style="background-color:#ecf0fe; margin:12px 8px 0 0; flex:1 0 auto">

[[Datei:Icon_Landingpage.png|30px]]Für Einsteiger<hr>

<ul style="font-size:0.8em; padding:0.7em 1em 1em 2.4em">


<li>[https://doc.expecco.de/w2.x/index.php?title=Was_ist_expecco%3F Allgemeine Informationen]</li>
<li>[[Expecco Usecases|Einsatzbereiche]]</li>
<li>[[Features|expecco Feature-List]]</li>
<li>[[Tutorials]]</li>
<li>[[usageHints/en|Hinweise zur Bedienung]]</li>
<li>[[Glossary|Begriffserklärung]] (Glossar)</li>

<li>[[FAQ]]</li>
</ul>
</div>

<div style="background-color:#ecf0fe; margin:12px 8px 0 0; flex:1 0 auto">

[[Datei:Icon_Landingpage5.png|30px]]Installation<hr>

<ul style="font-size:0.8em; padding:0.7em 1em 1em 2.4em">
<li>[[Installation]]</li>
<li>[[Installing additional Frameworks/en| Installation zusätzlicher Tools (Node, Python, ...)]]</li>
<li>[[Personal Settings|Persönliche Einstellungen]]</li>
<li>[[Configuration & Setup|Konfiguration]]</li>
<li>[[Anbindung expecco ALM]]</li>
<li>[[SAP_Testing|Anbindung expecco an SAP]]</li>
<li>[[Spezifische Anpassung]]</li>
<li>[[expecco UI]]</li>
<li>[[Expecco_Remote_Control_App|expecco Mobile Remote App]]</li>
<li>[[Probleme & Fehler]]</li>
</ul>
</div>

<div style="background-color:#ecf0fe; margin:12px 8px 0 0; flex:1 0 auto">

[[Datei:Icon_Landingpage4.png|30px]]Werkzeuge<hr>

<ul style="font-size:0.8em; padding:0.7em 1em 1em 2.4em">
<li>[[API von Elementaraktionen]]</li>
<li>[[Debugger]]</li>
<li>[[Editoren]]</li>
<li>[[Standard Libraries/Bibliotheken]]</li>
<li>[[Weitere Werkzeuge]]</li>
<li>[[Weitere Funktionen]]</li>
</ul>
</div>

<div style="background-color:#ecf0fe; margin:12px 8px 0 0; flex:1 0 auto">

[[Datei:Icon_Landingpage6.png|30px]]Reportgenerierung<hr>

<ul style="font-size:0.8em; padding:0.7em 1em 1em 2.4em">
<li>[[Report Generation|Reportgenerierung]]</li>
<li>[[Errors during Execution|Fehler während der Ausführung]]</li>
<li>[[Secret Strings|Geheime Zeichenketten und Passwörter]]</li>
</ul>
</div>

<div style="background-color:#ecf0fe; margin:12px 8px 0 0; flex:1 0 auto">

[[Datei:Erweiterung_plugin.png|30px]]Erweiterungen (Plugins)<hr>

<ul style="font-size:0.8em; padding:0.7em 1em 1em 2.4em">
<li>[[GUI Testing]]
<ul>
<li>[[Java GUI Plugins|Java Swing/FX/SWT UI Testing]]</li>
<li>[[Mobile Testing Plugin|Mobile Testing auf Android und iOS]]</li>
<li>[[WindowsAutomation Reference 2.0|UI Testing mit der Windows Automation Library]]</li>
<li>[[Selenium_WebDriver_Plugin|Web Testing mit Selenium WebDriver]]</li>
<li>[[VNC_Plugin_Reference|VNC UI Testing]]</li>
<li>[[GUI Testing|Weitere GUI Testing Plugins]]</li>
</ul>
</li>
<li>[[Schnittstellen zum SUT]]</li>
<li>[[ManualTest]]</li>
<li>Produktivität
<ul>
<li>[[GIT Plugin]]</li>
<li>[[HG Plugin (Mercurial)]]</li>
<li>[[CVS Plugin]]</li>
<li>[[Anbindung expecco ALM | expeccoALM Schnittstelle]]</li>
</ul>
</li>
<li>[[Weitere Plugins]]</li>
</ul>
</div>

<div style="background-color:#ecf0fe; margin:12px 8px 0 0; flex:1 0 auto">

[[Datei:Icon_Landingpage3.png|30px]]Elemente der Testsuite<hr>

<ul style="font-size:0.8em; padding:0.7em 1em 1em 2.4em">
<li>[[Tree Elements|Tree Elemente]]</li>
<li>[[Folder Element|Ordner]]</li>
<li>[[Testplan Element]]</li>
<li>[[Aktionen/Aktionsblöcke]]</li>
<li>[[Datatype Element|Datentyp Element]]</li>
<li>[[Inventory Element]]</li>
<li>[[Skill Element]]</li>
<li>[[Resource Element|Ressource Element]]</li>
<li>[[Attachment Element|Anhänge]]</li>
<li>[[ReportTemplate Element|Report Templates]]</li>
</ul>
</div>

<div style="background-color:#ecf0fe; margin:12px 8px 0 0; flex:1 0 auto">

[[Datei:Icon_Landingpage3.png|30px]]API Referenz (Elementarbausteine)<hr>

<ul style="font-size:0.8em; padding:0.7em 1em 1em 2.4em">
<li>[[API von Elementaraktionen|Übersicht]]</li>
<li>[[Expecco API#JavaScript_and_Smalltalk_Elementary_Blocks|Smalltalk & JavaScript]]</li>
<li>[[Expecco API#Groovy_Elementary_Blocks|Groovy]]</li>
<li>[[Expecco_API#Node.js_.28Bridged.29_Elementary_Blocks|NodeJS]]</li>
<li>[[Expecco_API#Bridged_Python_Elementary_Blocks|Python]]</li>
<li>[[Expecco_API#Bridged_Ruby_Elementary_Blocks|Ruby]]</li>
<li>[[Expecco_API#Bridged_C_Elementary_Blocks|C]]</li>
<li>[[Expecco API#VisualBasic_Elementary_Blocks|VisualBasic ]]</li>
<li>[[Expecco Scripting API|Shell und Script Languages]]</li>
 
<li>[[Useful API Functions|Useful API Functions:]]</li>
<ul>
<li>[[Number API Functions|Number API Functions]]</li>
<li>[[String API Functions|String API Functions]]</li>
<li>[[Collection API Functions|Collection API Functions]]</li>
<li>[[Filename API Functions|Filename API Functions]]</li>
<li>[[Stream API Functions|Stream API Functions]]</li>
<li>[[Date_and_Time_API_Functions|Date & Time API Functions]]</li>
</ul>
</ul>
</div>

<div style="background-color:#ecf0fe; margin:12px 8px 0 0; flex:1 0 auto">

[[Datei:Diagramm.png|30px]]Diagramm - Elemente<hr>

<ul style="font-size:0.8em; padding:0.7em 1em 1em 2.4em">
<li>[[DiagramElements-Step|Schritt]]</li>
<li>[[Pins (Ein - Ausgänge)]]</li>
<li>[[Code Ausführung]]</li>
<li>[[DiagramElements-Connection|Verbindung]]</li>
<li>[[DiagramElements-Pin|Pin Beschreibung]]</li>
<li>[[DiagramElements-Annotation|Notiz]]</li>
<li>[[DiagramElements-Probe|Messfühler]]</li>
</ul>
</div>

<div style="background-color:#ecf0fe; margin:12px 8px 0 0; flex:1 0 auto">

[[Datei:Refresh.png|30px]]Sonstiges<hr>

<ul style="font-size:0.8em; padding:0.7em 1em 1em 2.4em">
<li>[[Release Notes 26.x]]</li>
<li>[[Release Notes 25.x]]</li>
<li>[[Release Notes 24.x]]</li>
<li>[[Release Notes 23.x]]</li>
<li>[[Release Notes 22.x]]</li>
<li>[[Release Notes 21.x]]</li>
<li>[[Release Notes 20.x]]</li>
<li>[[Release Notes 19.x]]</li>
<li>[[Release Notes 18.x]]</li>
<li>[[Release Notes 2.x]]</li>
<li>[[Release Notes 1.x]]</li>
<li>[[Future releases expecco|Zukünftige Releases]]</li>
<li>[[Smalltalk]]</li>
</ul>
</div>

<div style="background-color:#ecf0fe; margin:12px 8px 0 0; flex:1 0 auto">

[[Datei:Beispiele_icon.png|30px]]Beispiele<hr>
Sie haben Fragen, wie ein Projekt aussieht?<hr>

<ul style="font-size:0.8em; padding:0.7em 1em 1em 2.4em">
 
<li>[[Beispiele | Hier finden Sie weitere Anwendungsbeispiele.]]</li>
<li>[[Expecco Code Snippets/en | Codeschnipsel]]</li>
</ul>
</div>

<div style="background-color:#ecf0fe; margin:12px 8px 0 0; flex:1 0 auto">

[[Datei:Beispiele_icon.png|30px]]Unterstützung weiterer Qualitätsmanagement Tools<hr>

<ul style="font-size:0.8em; padding:0.7em 1em 1em 2.4em">
<li>[[Jira_Plugin_Reference|Jira]]</li>
<li>[[PolarionPlugin_Reference|Polarion]]</li>
<li>[[Aqua_Plugin_Reference|Aqua]]</li>
<li>[[Starting_expecco_via_Command_Line#Integration_with_Jenkins|Jenkins Integration]]</li>

</ul>
</div>

</div>

<h2 style="clear:left">expecco ALM</h2>

<div style="display:flex; flex-wrap:wrap; padding:0; white-space:nowrap">
<div style="background-color:#ecf0fe; margin:12px 8px 0 0; flex:1 0 auto">

[[Datei:Sonstiges-Info.png|30px]]Allgemein<hr>

<ul style="font-size:0.8em; padding:0.7em 1em 1em 2.4em">
<li>[[Was ist expecco ALM?]]</li>
<li>[[Was ist der expecco Lizenzserver?]]</li>
<li>[[Anbindung expecco ALM]]</li>
<li>[[Rollen und Rechte]]</li>
<li>[[Filter]]</li>
<li>[[FAQ expeccoALM/en | FAQ]]</li>
</ul>
</div>

<div style="background-color:#ecf0fe; margin:12px 8px 0 0; flex:1 0 auto">

[[Datei:Icon_Landingpage5.png|30px]]Installation/Einrichten<hr>

<ul style="font-size:0.8em; padding:0.7em 1em 1em 2.4em">
<li>[[expecco ALM Installation|Installation]]</li>
<li>[[expecco ALM Installation Patches|expecco ALM Installation Patches]]</li>
<li>[[expecco ALM Einrichten Vorgehensweise|expecco ALM Einrichten]]</li>
<li>[[expecco ALM expecco Patch Service |Patchservice für expecco]]</li>
</ul>
</div>

<div style="background-color:#ecf0fe; margin:12px 8px 0 0; flex:1 0 auto">

[[Datei:Refresh.png|30px]]Plugins<hr>

<ul style="font-size:0.8em; padding:0.7em 1em 1em 2.4em">
<li>[[AIDYMO Jira|Atlassian Jira]]</li>
<li>[[CustomerSpecific|Kundenspezifische Portale]]</li>
</ul>
</div>

<div style="background-color:#ecf0fe; margin:12px 8px 0 0; flex:1 0 auto">

[[Datei:Refresh.png|30px]]Sonstiges<hr>

<ul style="font-size:0.8em; padding:0.7em 1em 1em 2.4em">
<li>[[expecco ALM App]]</li>
<li>[[Installation Lizenzserver]]</li>
<li>[[expecco ALM Release Notes|Release Notes]]</li>
<li>[[expecco ALM Known Issues|Known Issues]]</li>
</ul>
</div>
</div>

Settings ExternalScriptInterpreterSettings/en

2026-02-23T12:53:21Z

Sv: Änderung übernommen aus altem Wiki von cg, 19.11.25

== External Script Interpreter Settings ==

=== General Script Execution ===
===== Additional Path =====
Defines additional paths which are added to the $PATH environment variable (%PATH% on Windows).
This is passed to any external script interpreter. 
[[Datei:bulb.png|20px]]Notice, that paths are separated by ":" (colon) under Unix/Linux but ";" (semi) under Windows.
Additional paths are useful if a script calls for other programs, and you do not want to hardcode any paths in the script, in order to allow for the suite to be portable to other machines.

===== Environment Variables =====
Additional environment variables passed to external script interpreters.
To change, enter name and value and press "''Add''", or select a variable from the list and press "''Remove''".

== Subitems under External Script Interpreter Settings ==

* [[ Settings_ExternalScriptInterpreters_Shell_and_BatchSettings/en |Shell & Batch Settings]]
* [[ Settings_ExternalScriptInterpreters_GroovyClassPathSettings/en|Groovy Class Path Settings]]
* [[ Settings_ExternalScriptInterpreters_NodeSettings/en|Node Settings]]
* [[ Settings_ExternalScriptInterpreters_PythonSettings/en|Python Settings]]
* [[ Settings_ExternalScriptInterpreters_Jython_and_IronPythonSettings/en|Jython & IronPython Settings]]
* [[ Settings_ExternalScriptInterpreters_CBridgeSettings/en|CBridge Settings]]
* [[ Settings_ExternalScriptInterpreters_ClingSettings/en|Root/Cling Settings]]
* [[ Settings_ExternalScriptInterpreters_RubySettings/en|Ruby Settings]]
* [[ Settings_ExternalScriptInterpreters_DartSettings/en|Dart Settings]]
* [[ Settings_ExternalScriptInterpreters_JuliaSettings/en|Julia Settings]]
* [[ Settings_ExternalScriptInterpreters_SmalltalkSettings/en|Smalltalk Settings]]
* [[ Settings_ExternalScriptInterpreters_SchemeSettings/en|Scheme Settings]]
* [[ Settings_ExternalScriptInterpreters_OtherSettings/en|Other Settings]]

 
----

See also [[ Installing_additional_Frameworks/en |"Installing additional frameworks"]].

[[ Settings_ExternalScriptInterpreterSettings/en|Back to "External Script Interpreter Settings"]]
 
[[ Settings/en|Back to the main page "Settings"]]

[[Category:Settings]]

Settings SSDPSettings/en

2026-02-23T12:50:54Z

Sv: Änderung übernommen aus altem Wiki von cg, 19.11.25

== Enable SSDP Announcements ==

If enabled, expecco will announce its availability via SSDP multicast messages (also known as UPnP).
These announcements are especially useful for:
* the remote control app which runs on a mobile device
* other expeccos to detect possible execution partners
* expeccoALM to detect possible execution slaves
* administrators looking for machines which might have floating licenses allocated

[[Datei:bulb.png|20px]]Notice, that SSDP messages are UDP messages which are sent in regular time intervals,
and received within your local network (the site), depending on your router/switch and firewall setup.

To reduce traffic in the local network, some (usually bigger) organizations might disable, block or forbid SSDP announcements.
Or their spread may be limited to a subset of your machines (i.e. rooms/departments).
 Also, WLAN access points may have to be configured to forward these messages within the segment.

If in doubt, ask your administrator.

For your convenience, expecco includes a monitor window to show incoming SSDP messages ("''Extras''" → "''Debugging''" → "''Network Diagnose''" → "''SSDP Monitor''").

Folder Element/en

2026-02-23T12:48:51Z

Sv: Änderung übernommen aus altem Wiki von cg, 19.11.25

== Introduction ==
Folder elements are used to group related items. Notice that any action block item can have sub items. Besides being used to specify user-defined action menus (see [[Testsuite Editor-Metadata Editor/en | Testsuite Editor]]), folders have no special semantic relevance.

[[Datei:bulb.png|20px]]Notice that in contrast to other test tools, folders are NOT used to group testcases into test sequences or sub-activities into a composite activities. They are only used for organization - not to specify any execution order or execution behavior.

Folder elements only provide a single editor tab, into which documentation related to the folder can be entered. If this documentation is left empty, the documentation editor presents a short summary of the containing element's documentation texts (read-only).

== Useful Tricks ==

=== Public vs. Private Actions ===

In imported library suites, put stuff which is supposed to be used by importing projects into a separate folder named "API" or "Exported". This makes it easier for other team members to find reusable stuff. You may also want to change the folder's icon color (contextMenu → "''Misc''" → "''IconColor''") to emphasize particular folders (such as "red" for obsolete or experimental actions, "green" for released/public actions etc.)

=== Demos and Examples ===

Add a folder named "Playground", "Sandbox" or "Examples" or similar and place compound action blocks which demonstrate key features or low level access functionality. Other team members may later easily find those and play with the examples. It is also a good idea to place simple connection, communication, [[Glossary/en#SUT_.28System_Under_Test.29|SUT]] is running tests, setup and shutdown blocks there (unless those are commonly used, then put them into API/Exported).

=== Define Useful Actions as Menu Functions ===

Add a folder named "menu Actions" or similar, place and useful actions for test setup, equipment startup and shutdown or calibration into it. When this folder is defined as the project's operation menu folder (in the test suite's "Misc" editor page), you can quickly execute those functions via the main menu. For more information, see [[User Defined Menu Items]].

== See Also ==

[[Tree Elements]]
 [[ Navigation Tree ]]

[[Category: Tree Elements]]

Settings WindowsAutomationSettings/en

2026-02-23T12:47:06Z

Sv: Änderung übernommen aus altem Wiki von cg, 25.11.25

[[Datei:bulb.png|20px]]Notice: The Windows Automation Plugin (WA V1) has been replaced by a new version,
and is only maintained to provide backward compatibility for customers using it.
Please migrate to use the WA2 Plugin, which is described in
"[[WindowsAutomation_Reference_2.0/en| WindowsAutomation Reference 2.0]]".

== Windows-Automation Plugin Settings ==

The Windows-Automation plugin extends the GUI-browser's capabilities to support recording, replay and testing of GUI applications via the Windows-Automation technology.

This settings dialog is only shown/enabled if the plugin is loaded and licensed.
----
Back to [[Online Documentation]]

[[Category: Settings]]

WindowsAutomation Reference 2.0/en

2026-02-23T11:49:22Z

Sv: /* Known issues in the current Release 19.1.0 */

This is the documentation for the Windows Automation 2.0 plugin.
It provides facilities to automate tests incorporating applications with a GUI based on Windows Presentation Foundation (WPF), WinForms, and the old Win32 API.

Notice: The vsn2 replaces the previous vsn1 plugin, which is no longer maintained.
The change was necessary due to changes in the Windows operating system, and features which were discontinued by Microsoft.
The vsn2 plugin uses Microsoft's UI-Automation2 API to interact with the application.
This API was not avaliable in Windows-XP, Vista and other older OS versions, and many features used by the previous version are no longer supported in newer OS versions, or need different parameters.

=Features=
*Automated GUI testing of WPF, WinForms, and Win32 applications.
*Contains an expecco block library and tools which help to model tests and inspect the GUI of the application.
*Parallel remote test-execution on multiple systems.
*Performs tests against already built executables. No source code changes / recompilation of the application is required.
*Access to GUI components using XPath locators.
*Access objects of the application live at execution time.
*Full access to keyboard and mouse of the target system.
*Lots of additional features such as screen capturing, taking screenshots, highlighting GUI elements, mouse tracking, ...

= Known issues in release 19.1.0 =
* The WindowsAutomation2.ets library has got a new functional id. When reimporting the library in existing Pre-19.1.0 test suites (which is mandatory), a warning about a changed functional id is shown once. It is ok to accept this dialog.
* Instant follow mouse is very expensive in Windows and is therefore disabled. Use ''HotKeys'' to select a GUI element in the tree at the current pointer position or to update the element tree. HotKeys can be configured in the settings. The HotKey-service has to be started. Take care that the keys have not already been grabbed by another application. If that is the case, a warning will be shown, and you should either make sure that expecco is started before the other application, or that you use other hotkey combinations (in either expecco or the application).

= Limitations =
* WindowsAutomation only supports XPath1.0.
: That means for example, that the "ends-with" function, which is an XPath2 function, is not supported and thus not possible as XPath attribute filter.
: See [[https://en.wikipedia.org/wiki/XPath_2.0#Function_library XPath vs. XPath2]] for details. For some (especially "ends-with") there are workarounds by comparing against a substring which is based on the length of the attribute string or a regex match (see [https://stackoverflow.com/questions/40934644/xpath-testing-that-string-ends-with-substring]).
: Notice, that this is a limitation of the Windows operating system, which cannot be worked around in expecco.

=Installation and Connection=
The WindowsAutomation testing plugin uses the expecoo ".NET-Bridge" which consists of two parts: A plugin for expecco, and a server executable using the .NET framework running on the remote computer to connect to.

==Requirements==
On the machine running the system under test:
*.NET Framework 4.7 [https://www.microsoft.com/net/download/all] or higher.
* One of the following operation systems:
::- Windows 7 SP1
::- Windows 8
::- Windows 8.1
::- Windows 10
::- Windows 11

::- Windows Server 2012 R2
::- Windows Server 2016
::- Windows Server 2019
::- Windows Server 2022

==Plugin Components==
The plugin consists of the following parts:
* The [[GUI Browser]], used to interactively explore your application.
* The Windows Automation Library, which provides blocks that you can use in your test cases.
* The .NET-Bridge server, which provides an interface between the application under test and expecco.

==Installing and Configuring the Plugin in Expecco==
The plugin is usually installed automatically by the installer; either included in the main expecco installation or provided as a separate installable add-on package. Its files are stored in the "<code>plugin</code>" subfolder of the expecco installation folder. You can also copy those files manually to that folder, if required. Expecco detects the plugin automatically during startup. You may have to restart your expecco session, if the plugin is installed later.

==Preparing a local system for test execution==
To automate applications running on the SAME host as expecco, there is no need to set up anything - it should work out of the box.

Try to connect to an application via the GUIBrowser's ''WindowsAutomation''-connect dialog:

[[Datei:WindowsAutomation2Connect.png]]

==Preparing a remote system for test execuction==

===Security Considerations===
Please make sure, that remote access is only possible from inside a secure local network.
Under no circumstances should you grant access to the DotNetBridgeServer from untrusted hosts.

===DotNet Bridge Server===

The remote system has to run the "''.Net-Bridge server''" which in turn either actively connects to expecco or passively waits for an incoming connection from expecco.

For this, copy "<code>DotNetBridgeServer.exe</code>" and "<code>DotNetBridge.dll</code>" (found in the "<code>packages/exept/bridgeFramework/dotNetBridge/dotNetBin</code>" folder under the expecco installation directory) to the computer where your system under test is running (you can copy it into any folder). No further installation is needed.

To start the bridge, navigate to the executable in a shell/cmd/console and start it with the following arguments
("<code>DotNetBridgeServer.exe --help</code>" outputs a list of valid options):
{| class="wikitable"
|-
! Arguments !! Required !! Description
|-
| -s || Yes || "''server mode''". Tells the executable to run in server mode (it will wait for expecco to connect to it, as opposed to client mode, where it actively connects to the partner).
|-
| -k || Yes || "''keepalive''". Tells the client to keep the connection open after a connection has been terminated. This saves you the hassle to restart it every time a test finishes.
|-
| -a <ip/hostname>|| Yes || "''IP address accepting connections''". The IP-address or hostname of an interface on the host on which connections will be accepted (in server mode) or to which it connects (in client mode). If you have multiple network interfaces, you can ensure that only incoming connections on the secure network will be accepted by setting the IP address of this interface. To allow incoming connections on any network interface (i.e. to have it listen on any IP-address), set it to 0.0.0.0. If you are not inside a secure network, you should use a secure tunnel (e.g. a SSH or Powershell tunnel) between the machine running expecco and the machine running the bridge and listen only on 127.0.0.1 (the default).
|-
| -p <int> || No || "''port''". The port the server should listen on (in server mode) or to which is should connect (default is 34318).
|-
| -L <string> || No || "''assembly''". Load a .NET assembly on startup. Omit the .dll extension (so use "WindowsAutomation" but not "WindowsAutomation.dll"). You can repeat this option to load multiple assemblies.
Note: this is not normally needed, as expecco loads the required assemblies automatically into the bridge. However, if security settings forbid external assemblies, you have to copy them to the target machine, and load them via command line option.
|}

So you may execute on the remote host:

DotNetBridgeServer.exe -s -k -a 0.0.0.0

For automatic tests, you must setup the target system for the bridge server to be running; either by adding it to some "auto exec' script, or by adding to the "scheduled tasks", or by remote starting it from your test-host via a powershell script, remote ssh command or similar.

If you get an "Assembly not Found" error, you may have an incompatible .NET framework or the "DotNetBridge.dll" is missing. If you get a network error, or the expecco-host cannot connect, make sure that your firewall settings allow access to the given ports (you may try an alternative port like 8080, which must then be specified on both sides).

=Settings=
There are currently no configurable settings.

=GUI Browser=
The GUI browser is used to explore a running application. You can browse the application, inspect element properties and execute actions. See "[[GUI Browser| Expecco GUI Tests Extension Reference]]" for details.

=Library=
This article gives a short overview over the design philosophy of the library. You can find more detailed documentation and examples attached to the blocks itself.

== Connect to Application vs. Connect to Screen ==
You can either "connect to a single application", or "connect to the screen".
The first provides faster access to the components, but will not work, if the app creates subprocesses with a GUI (eg. for dialogs or additional windows). There exist also applications which always create a subprocess, even for the main GUI.

For such applications, you have to "connect to the screen", and provide an additional window-reference in the XPath locator.
 You must also use a screen connection, if your test contains interactions between multiple top-level windows, for example a drag&drop between windows.

== Connecting to an Application ==
To automate an application, you first have to connect to it or to its screen. You can do this with the
blocks from the "''Connecting''" group.
[[Bild:WindowsAutomation2_Library_ConnectingBlocks.PNG|frame|The Library's Connection Blocks (old picture without screen connection blocks).]]

You can connect to an individual application by its ''executable name'', or by its ''process id''.
If you use the executable name, expecco will attach to the main process of the specified executable.
Be careful as this is not necessarily the process drawing the GUI!
Use the process id if an application spawns more than one process and you need to make sure you connect to the GUI process and not some background process.

All connection blocks also require you to specify a ''name'' by which the connection should be known in future.
This is needed when you automate multiple applications at the same time and need to change
''connection contexts'' during test execution.
Please note that the application to connect to has to be started before the corresponding connection block is executed.
You can change in context of which connection a block is executed with the [''Set Active Connection''] block.
This allows you, for example, to automate and compare the state of applications running on multiple systems in one test case.

=== Establishing a Local Connection ===
To automate an application running on the same host as expecco, there is no need to set up anything.
Use "[''Create Local Connection'']" with the above mentioned parameters.

=== Establishing a Remote Connection ===
Make sure that the DotNet-Bridge server ("<code>DotNetBridgeServer.exe</code>") is running on the remote system, as explained in the chapter [[#Preparing a remote system for test execuction|"''Preparing a remote system for test execuction''"]]
When the bridge is running, you can connect to it with the "[''Create Remote Connection'']" block using the hostname and IP-Address you specified when you started the bridge.

Notice, that the DotNet-Bridge server only accepts local connections by default.
This is done for security reasons. Use the "-a x.x.x.x" command line argument to specify, which hosts are allowed
to connect. With "-a 0.0.0.0", any host is allowed. Do NOT use this, if the remote host is reachable from untrusted hosts.

=== Closing a Connection ===
Remember to always close a connection when it is no longer needed, as it otherwise needlessly consumes resources.
One simple way to do this is to setup your connection in the "''Before Execution''" (pre-action) part of the test suite or test case,
and put the "[''Close All Connections'']" action block in the "''After exeuction''" (post-action) part.

 

== Accessing GUI Elements ==
[[Bild:WindowsAutomation_Library_AccessBlocks.PNG|frame|The Library's GUI Element Access Blocks.]]
[[Bild:WindowsAutomation_Library_AccessBlocksExamples.PNG|frame|A Few Examples on How to Access Elements in Notepad.]]
[[Bild:WindowsAutomation_Library_AccessBlocksModes.PNG|frame|Different Ways to Reference a GUI Element.]]
All Windows applications are built as a '' tree'' of '' GUI elements''.
Some elements act as container of other element - their children. Tables, for example, are containers
for their cell elements which themselves might contain text labels.
At the root of the tree are one or more ''windows'' . When you connect to an application, you get access to
all windows at the tree's root.
To manipulate any of the system under test's GUI element, you first have to gain access to it.
The group named "''GUI Element Access''" provides action blocks to access elements. The actions are further categorized into sub-groups named "'' Access By XPath''" , "''Access By Property''", "''Existence Test''" etc.
For each category, blocks with the same interface exist. The only difference is the method of retrieval.

;Get GUI Element : returns a ''single'' GUI element matching the search condition. If multiple elements match the condition, an ''arbitrary'' element matching the condition is returned.
:To make sure that there is only one single element matching, set ''ensureExclusive'' to true. You can also enforce this globally by setting the environment variable "''ensureExclusive''" in your environment.
:If ensureExclusive is set and more than one element is found, the block will fail and notify about the ambiguity. This is disabled by default, as checking for uniqueness is a very costly (ie. slow) operation.
:You can also specify a ''timeout'' after which the search is aborted. This is useful if you know an element should be there already (or soon but might currently be loading).

;Get GUI Elements: returns ''all'' GUI elements matching the search condition. If no element is found, it returns an empty list ''Timeout'' and ''cacheXPath'' are also applicable.

;Exists: Works exactly the same as ''Get GUI Element'' but does not fail if no element is found. Additionally provides an output pin specifying if an element has been found.

Both of these blocks are also available in the "''Relative To Anchor''" variety. Those blocks also take a GUI Element as ''anchor'' in relation to which they search.

=== Using XPaths ===

'''XPath''' is the query language used to select GUI elements in the application's element tree.
You can find the XPath of an element with the [[Expecco GUI Tests Extension Reference/en|Gui Browser]] or with third-party applications like "Inspect.exe" [https://msdn.microsoft.com/en-us/library/dd318521(v=vs.85).aspx] or "FlaUInspect" [https://github.com/FlauTech/FlaUInspect].
 As an example, the full ''XPath'' of the scroll button on the
vertical scrollbar in the german Windows "Notepad.exe" application looks like this:

<code>/Window[@Name='Unbenannt - Editor']/Document[@Name='Text-Editor']/ScrollBar[@Name='Vertikale Bildlaufleiste']/Button[@Name='Bildlauf nach unten'] </code>

For each level in the GUI tree, a new ''Location Step'' containing the child element's ''Control Type'' was added in the above XPath.
 You do not have to use any predicates, the following XPath is valid as well:

<code>/Window/Document/ScrollBar/Button </code>

but might lead to issues if multiple GUI Elements match this path.

You can select by three predicates (which can be mixed and matched in the same query):

; Name: the name the application developer has given an element. Be careful as this name might change during programm execution (See for example Notepad's window name which always begins with the name of the currently opened file).
: <code>/Window[@Name='Unbenannt - Editor'] </code>

; AutomationId: An ID the application developer has given an element. It is meant to be unique between siblings but that is not enforced on lazy or incompetent programmers.
: Many lazy developers leave the ID empty or reuse it, making it useless.
: You should use this ID wherever applicable as it is static and meant for this exact purpose.
: <code>/Window/Document[@AutomationId='15'] </code>

;List Index: If there are multiple siblings with the same Control Type, you can select one of them by (1-based) list index.
: <code>/Window[1]/Document[1] </code>
: <code>/Window[1]/Document[last()] </code>

=== Warning there are XPath Limitations ===
'''Please Note''': You can ONLY use the three predicates above in your XPaths.
 Other predicates '''DO NOT''' work!
 To search for an element by another property (e.g. its help text), use the '''By Property''' variant of the block instead.
If the property is not unique, you can select a unique ancestor of the target by property or XPath relative to which the property is unique.
You can then use that ancestor as anchor in the [''Get GUI Element By Property (Relative to Anchor)''] block.

=== Using Wildcards in XPaths ===

XPath also supports '''wildcards'''. You can:
* replace '''one tree level''' with a "*" wildcard:
: <code>/Window/Document[@AutomationId='15']/*/Button[1]</code> 
: <code>/*/*/*/Button[1] </code>

* replace a '''control type''' with a "*" wildcard:
: <code>/Window/*[@AutomationId='15'] </code>

* replace '''an arbitrary amount of levels''' with a "//" wildcard:
: <code>//Button </code> 
: <code>/Window//Button[1] </code>

Especially the last option is useful as it makes your tests more readable, in that the reader can easily focus on the relevant parts of the xpath.

But be careful: using wildcards comes at a steep performance cost (due to the implementation inside the Windows API).
If your test runs unacceptably slow, first try to remove wildcards where they are not needed.

=== Using Properties===

You can also search for elements by property; i.e. by specifying a value an element's property with the given name must have.

For a list of properties a GUI element might have, take a look at Microsoft's documentation [https://docs.microsoft.com/en-us/dotnet/framework/ui-automation/ui-automation-control-patterns-overview#control-pattern-classes-and-interfaces].

=== XPath Resolution in Action Blocks ===

Xpath resolution may be slow in the Windows Automation API, depending on the number of windows/elements which have to be checked.

To speed up test execution, you should reuse a resolved XPath if possible.
For this, use the "Get Element by XPath" action, and feed the "element handle" to multiple actions.
All action- and property access blocks can take either an XPath or an element handle as locator input.

The image on the right shows this mode in action. Variants 1 and 2 are functionally equivalent.
While Variant 2 is more concise, Variant 1 is the right choice in most cases. While it has an additional block, you have control over the other input parameters.
You also can recycle the GUI element reference as seen in 3). This is invaluable as the XPath only has to be resolved once. This speeds up test execution by a lot as XPath resolution is very expensive operation.

'''Rule of thumb''': Always use Variant 1 except if you need the reference to the GUI element only once, or if the application replaces the element dynamically.

=== Separating Path Definitions ===

It is highly recommended to add definitions for element-paths into an environment (typically the project environment), and use "Environment Value" references as input to the steps. This gives two benefits:

* the paths are hidden and the values at the steps become more readable
* your tests are easier to maintain: in case of a changed window layout/structure, only the variable definitions need to be changed at one place.
* you can import those definitions from a CSV or XML file, and thus separate the locators from the actual test suite. In case of changed UI-layout / UI-hierarchy after a revision change of the tested application, all you need is a new excel or xml file containing those definitions.

If the development team of the application can provide the paths of the UI components in a machine readable form (i.e. CVS or XML file), you may even let expecco read and parse those path definitions at test start time, and let it automatically adapt to any change.

 

== Interacting with GUI Elements ==
Once you retrieved a GUI element, you can interact with it by making use of the library's blocks located in the groups '''Elements''', '''Patterns''', and '''Properties'''.
Blocks in those categories take a GUI Element (and sometimes additional data) as input and manipulate it or query for its properties in some way.

[[Bild:WindowsAutomation_Library_ElementsPatternsProperties.png|600px|The Library's Blocks for Interacting With Elements.]]

=== The 'Elements' Group ===

This group contains blocks that are applicable to blocks that only work on GUI elements of a specific type. For a block's detailed description with examples ,
take a look at the block's documentation in expecco.

Even though not only Checkboxes can be 'checked', the [''Check''] block in the "''Checkbox group''" only works for checkboxes and not e.g. for radio buttons.
Because of this limitation there are not that many blocks targeting specific elements. Most blocks target a specific ''pattern'' instead and are therefore in the "''Patterns''" group.

=== The 'Patterns' Group ===

This group contains blocks that are applicable to GUI elements supporting a certain ''pattern''.
Patterns describe how a GUI element ''behaves'' rather than what it ''is''. An element can also support multiple patterns at the same time.
You can find out which patterns an element supports with the [''Get Supported Patterns''] block or by taking a look at Microsoft's documentation about patterns [https://docs.microsoft.com/en-us/dotnet/framework/ui-automation/ui-automation-control-patterns-overview].

Pattern blocks can therefore be ''re-used'' between GUI elements of different types.
For example, the [''Expand''] block in "''ExpandCollapse pattern''", can be used to expand Comboboxes, Menus, Submenus, or Trees.

=== The 'Properties' Group ===

Blocks in the "''Patterns''" and "''Elements''" group already allow you to query the value of properties pertaining to that element or pattern. Blocks in the "''Properties''" group allow you to query both properties which all elements share as well as arbitrary properties. If you try to retrieve a property an element does not support, the block will fail.

Please note that the [''Get Arbitrary Property''] block can only query for properties that belong to a pattern. You cannot, for example, query "Text" from a textfield as this is not a property, use "Value" of the value pattern instead. Microsoft's documentation has a list of patterns and the properties they provide [https://docs.microsoft.com/en-us/dotnet/framework/ui-automation/ui-automation-control-patterns-overview#control-pattern-classes-and-interfaces]

 

== Automating Keyboard and Mouse ==
[[Bild:WindowsAutomation_Library_KeyboardMouse.png|400px|The Library's Blocks for Interacting With Keyboard and Mouse.]]

You can control keyboard and mouse with action blocks in the "''Keyboard''" and "''Mouse''" groups, as shown on the right. In contrast to the blocks above, which work in context of a GUI element, the keyboard and mouse blocks work on a global level. You therefore do not need to provide a GUI element when using them.

You might want to execute some blocks in context of a GUI elemenet nontheless (e.g. enter a number into a text field instead of just pressing keys while the application is running). You can achieve this by selecting the element with the mouse beforehand as you would do when using the application normally (use the [''Left/Double/Right Click On Element''] blocks for this).
If you do not want to wait for the mouse to move, you can also use the [''Set Focus''] block instead.

=== Keyboard ===
The plugin provides blocks to interact with the keyboard on different abstraction levels. The most versatile block is [''Type With Control Keys Pressed''] where you can specify a string of characters to be typed while any number of control keys (e.g. "esc", "alt", "shift", "ctrl", ...) are held down. All other blocks are specializations of this block.

[''Press Control Keys''] e.g. allows you to enter key commands such as renaming files ("ALT+F2"), starting the task manager ("CTRL+ALT+DEL"), or closing a window ("ALT+F4"). [''Press Control Key''] makes it easy to just press a single key (e.g. "RETURN" to start a new line in an edit box). The "''Shortcuts''" group provides an assorted collection of often used key combinations for your convenience.

Use the [''Type''] action to just type some text, or if you just need some throwaway demo text, use [''Type Random Phrase''].

If you need more fine grained control over the keyboard, you can make use of ''Scan Codes''. The keyboard sends a scan code to the operating system whenever a key is pressed or released.
Microsoft provides a list of the scan codes it supports [https://docs.microsoft.com/en-us/previous-versions/visualstudio/visual-studio-6.0/aa299374(v=vs.60)].
[''Press Key By Scan Code''] sends a signal to Windows that a key with a given scan code has been pressed (and is held down). The matching [''Release Key By Scan Code''] sends Windows the adverse signal.
Please note that a key that is pressed, stays pressed until it is explicitly released. If you want to just press and release a key by scan code, use [''Type Key By Scan Code''].

=== Mouse ===
The plugin provides blocks manipulating the mouse in three ways: ''Clicking'', ''Moving'', and interacting with its ''Buttons''.

 

== Recording and Taking Screenshots ==

= Frequently Asked Questions =

== Some elements are not presented in the UI browser's tree ==
This happens if the application "draws" elements (such as checkboxes, buttons or text) without using Windows widgets and without providing proper automation support (btw: which a well behaved application should, because this also affects/prevents usability and makes these controls inaccessable to eg. users with vision disabilities).
We encountered such in table-views containing checkboxes (probably OLE embedded database-tables).
These elements must be addressed either via coordinates (relative to the containing parent element), or via an image search (grab and define the image in the GUI browser). Both have disadvantages and are inconvenient, but there is no other technical solution.

== What is the difference between Click/Invoke/Select/Toggle? ==
Click sends a click event; Invoke calls directly into the application's or widget's event handler; Select and Toggle usually call the corresponding automation functions (if the app-programmer provided that).

A click generates a click event to the widget; may disfunction if the widget is invisible or covered (eg. by a tooltip).

An invoke skips over the event mechanism and calls the event hander directly. It may also not work, if the event handler insists on keyboard focus, mouse position, shift- or ctrl-key or other state.

There exists no mechanism which work with any application: for some, you will have to record a mouse-move and/or a set-focus for the click to work.
If possible, disable tooltips and other automatically appearing popups in the target app.

If none works, try the click at screen position action (which generates a real mouse-click, not via UI-automation to the widget, but via the Windows Event Queue). This should work in any case, but suffers most from popups, mouse position and keyboard focus.

== My element supports a certain pattern but blocks of that pattern don't work ==

== I have designed custom elements, how can I automate them? ==

== I have extended my GUI elements to have custom properties, how can I query them? ==

== Hotkey "Get hovered element" selects the wrong element in the tree ==

Sometimes there are elements which overlap or hide other elements. This element is then selected in the tree. In this case, you can use the Hotkey "Get focused element" to select the element in the tree

== DevExpress controls are not visible in the GUI Browser ==

DevExpress has some possibilities to disable UIAutomation support, which is also used by expecco.If you can't see one or some controls, please check e.g. https://supportcenter.devexpress.com/ticket/details/bc4069/devexpress-controls-now-clear-ui-automation-peers-for-the-application and other information on the DevExpress Support Site.

== Connect fails with "Permission Denied" ==
Some apps required admin access rights to connect to.
You will get a "failed to connect" error and a walkback which looks like:

Could not connect to application: wireguard
System.ComponentModel.Win32Exception (0x80004005): Access denied
bei System.Diagnostics.ProcessManager.OpenProcess(Int32 processId, Int32 access, Boolean throwIfExited)
bei System.Diagnostics.NtProcessManager.GetModuleInfos(Int32 processId, Boolean firstModuleOnly)
bei System.Diagnostics.NtProcessManager.GetFirstModuleInfo(Int32 processId)
bei System.Diagnostics.Process.get_MainModule()
bei FlaUI.Core.WindowsAPI.WindowsApiTools.GetMainModuleFilepath(Process process)
bei FlaUI.Core.Application.Attach(Process process)
bei WindowsAutomation.Application..ctor(String name, UIA3Automation automation, PropertyRepository propertyRepository, String windowTitle)
bei WindowsAutomation.Client.GetApplication(String name, String windowTitle)

You have two options:
* run expecco as admin
* start a dotNet-bridge manually as admin (in the local or remote machine):
...\bridgeFramework\dotNetBridge\dotNetBin>DotNetBridgeServer.exe -k -s -a 0.0.0.0 -p 34319
: then create a "remote connection" to it.

== Execution of GUI Actions blocks after Mouse Down ==
UI Automation is blocking further execution of some blocks after a mouse button <Press>.

== Unable to interact with application (SUT) after Startup ==
In some cases - e.g. starting the test via Jenkins - the application (SUT) is not in the correct state after startup. You can't find elements and/or actions fail.
You can try to send "[WA]Window - Normalize" with the path of the window to solve this

WindowsAutomation Reference 2.0/en

2026-02-23T11:48:34Z

Sv: Änderung übernommen aus altem Wiki von cg, 29.11.25

This is the documentation for the Windows Automation 2.0 plugin.
It provides facilities to automate tests incorporating applications with a GUI based on Windows Presentation Foundation (WPF), WinForms, and the old Win32 API.

Notice: The vsn2 replaces the previous vsn1 plugin, which is no longer maintained.
The change was necessary due to changes in the Windows operating system, and features which were discontinued by Microsoft.
The vsn2 plugin uses Microsoft's UI-Automation2 API to interact with the application.
This API was not avaliable in Windows-XP, Vista and other older OS versions, and many features used by the previous version are no longer supported in newer OS versions, or need different parameters.

=Features=
*Automated GUI testing of WPF, WinForms, and Win32 applications.
*Contains an expecco block library and tools which help to model tests and inspect the GUI of the application.
*Parallel remote test-execution on multiple systems.
*Performs tests against already built executables. No source code changes / recompilation of the application is required.
*Access to GUI components using XPath locators.
*Access objects of the application live at execution time.
*Full access to keyboard and mouse of the target system.
*Lots of additional features such as screen capturing, taking screenshots, highlighting GUI elements, mouse tracking, ...

= Known issues in the current Release 19.1.0 =
* The WindowsAutomation2.ets library has got a new functional id. When reimporting the library in existing Pre-19.1.0 test suites (which is mandatory), a warning about a changed functional id is shown once. It is ok to accept this dialog.
* Instant follow mouse is very expensive in Windows and is therefore disabled. Use ''HotKeys'' to select a GUI element in the tree at the current pointer position or to update the element tree. HotKeys can be configured in the settings. The HotKey-service has to be started. Take care that the keys have not already been grabbed by another application. If that is the case, a warning will be shown, and you should either make sure that expecco is started before the other application, or that you use other hotkey combinations (in either expecco or the application).
= Limitations =
* WindowsAutomation only supports XPath1.0.
: That means for example, that the "ends-with" function, which is an XPath2 function, is not supported and thus not possible as XPath attribute filter.
: See [[https://en.wikipedia.org/wiki/XPath_2.0#Function_library XPath vs. XPath2]] for details. For some (especially "ends-with") there are workarounds by comparing against a substring which is based on the length of the attribute string or a regex match (see [https://stackoverflow.com/questions/40934644/xpath-testing-that-string-ends-with-substring]).
: Notice, that this is a limitation of the Windows operating system, which cannot be worked around in expecco.

=Installation and Connection=
The WindowsAutomation testing plugin uses the expecoo ".NET-Bridge" which consists of two parts: A plugin for expecco, and a server executable using the .NET framework running on the remote computer to connect to.

==Requirements==
On the machine running the system under test:
*.NET Framework 4.7 [https://www.microsoft.com/net/download/all] or higher.
* One of the following operation systems:
::- Windows 7 SP1
::- Windows 8
::- Windows 8.1
::- Windows 10
::- Windows 11

::- Windows Server 2012 R2
::- Windows Server 2016
::- Windows Server 2019
::- Windows Server 2022

==Plugin Components==
The plugin consists of the following parts:
* The [[GUI Browser]], used to interactively explore your application.
* The Windows Automation Library, which provides blocks that you can use in your test cases.
* The .NET-Bridge server, which provides an interface between the application under test and expecco.

==Installing and Configuring the Plugin in Expecco==
The plugin is usually installed automatically by the installer; either included in the main expecco installation or provided as a separate installable add-on package. Its files are stored in the "<code>plugin</code>" subfolder of the expecco installation folder. You can also copy those files manually to that folder, if required. Expecco detects the plugin automatically during startup. You may have to restart your expecco session, if the plugin is installed later.

==Preparing a local system for test execution==
To automate applications running on the SAME host as expecco, there is no need to set up anything - it should work out of the box.

Try to connect to an application via the GUIBrowser's ''WindowsAutomation''-connect dialog:

[[Datei:WindowsAutomation2Connect.png]]

==Preparing a remote system for test execuction==

===Security Considerations===
Please make sure, that remote access is only possible from inside a secure local network.
Under no circumstances should you grant access to the DotNetBridgeServer from untrusted hosts.

===DotNet Bridge Server===

The remote system has to run the "''.Net-Bridge server''" which in turn either actively connects to expecco or passively waits for an incoming connection from expecco.

For this, copy "<code>DotNetBridgeServer.exe</code>" and "<code>DotNetBridge.dll</code>" (found in the "<code>packages/exept/bridgeFramework/dotNetBridge/dotNetBin</code>" folder under the expecco installation directory) to the computer where your system under test is running (you can copy it into any folder). No further installation is needed.

To start the bridge, navigate to the executable in a shell/cmd/console and start it with the following arguments
("<code>DotNetBridgeServer.exe --help</code>" outputs a list of valid options):
{| class="wikitable"
|-
! Arguments !! Required !! Description
|-
| -s || Yes || "''server mode''". Tells the executable to run in server mode (it will wait for expecco to connect to it, as opposed to client mode, where it actively connects to the partner).
|-
| -k || Yes || "''keepalive''". Tells the client to keep the connection open after a connection has been terminated. This saves you the hassle to restart it every time a test finishes.
|-
| -a <ip/hostname>|| Yes || "''IP address accepting connections''". The IP-address or hostname of an interface on the host on which connections will be accepted (in server mode) or to which it connects (in client mode). If you have multiple network interfaces, you can ensure that only incoming connections on the secure network will be accepted by setting the IP address of this interface. To allow incoming connections on any network interface (i.e. to have it listen on any IP-address), set it to 0.0.0.0. If you are not inside a secure network, you should use a secure tunnel (e.g. a SSH or Powershell tunnel) between the machine running expecco and the machine running the bridge and listen only on 127.0.0.1 (the default).
|-
| -p <int> || No || "''port''". The port the server should listen on (in server mode) or to which is should connect (default is 34318).
|-
| -L <string> || No || "''assembly''". Load a .NET assembly on startup. Omit the .dll extension (so use "WindowsAutomation" but not "WindowsAutomation.dll"). You can repeat this option to load multiple assemblies.
Note: this is not normally needed, as expecco loads the required assemblies automatically into the bridge. However, if security settings forbid external assemblies, you have to copy them to the target machine, and load them via command line option.
|}

So you may execute on the remote host:

DotNetBridgeServer.exe -s -k -a 0.0.0.0

For automatic tests, you must setup the target system for the bridge server to be running; either by adding it to some "auto exec' script, or by adding to the "scheduled tasks", or by remote starting it from your test-host via a powershell script, remote ssh command or similar.

If you get an "Assembly not Found" error, you may have an incompatible .NET framework or the "DotNetBridge.dll" is missing. If you get a network error, or the expecco-host cannot connect, make sure that your firewall settings allow access to the given ports (you may try an alternative port like 8080, which must then be specified on both sides).

=Settings=
There are currently no configurable settings.

=GUI Browser=
The GUI browser is used to explore a running application. You can browse the application, inspect element properties and execute actions. See "[[GUI Browser| Expecco GUI Tests Extension Reference]]" for details.

=Library=
This article gives a short overview over the design philosophy of the library. You can find more detailed documentation and examples attached to the blocks itself.

== Connect to Application vs. Connect to Screen ==
You can either "connect to a single application", or "connect to the screen".
The first provides faster access to the components, but will not work, if the app creates subprocesses with a GUI (eg. for dialogs or additional windows). There exist also applications which always create a subprocess, even for the main GUI.

For such applications, you have to "connect to the screen", and provide an additional window-reference in the XPath locator.
 You must also use a screen connection, if your test contains interactions between multiple top-level windows, for example a drag&drop between windows.

== Connecting to an Application ==
To automate an application, you first have to connect to it or to its screen. You can do this with the
blocks from the "''Connecting''" group.
[[Bild:WindowsAutomation2_Library_ConnectingBlocks.PNG|frame|The Library's Connection Blocks (old picture without screen connection blocks).]]

You can connect to an individual application by its ''executable name'', or by its ''process id''.
If you use the executable name, expecco will attach to the main process of the specified executable.
Be careful as this is not necessarily the process drawing the GUI!
Use the process id if an application spawns more than one process and you need to make sure you connect to the GUI process and not some background process.

All connection blocks also require you to specify a ''name'' by which the connection should be known in future.
This is needed when you automate multiple applications at the same time and need to change
''connection contexts'' during test execution.
Please note that the application to connect to has to be started before the corresponding connection block is executed.
You can change in context of which connection a block is executed with the [''Set Active Connection''] block.
This allows you, for example, to automate and compare the state of applications running on multiple systems in one test case.

=== Establishing a Local Connection ===
To automate an application running on the same host as expecco, there is no need to set up anything.
Use "[''Create Local Connection'']" with the above mentioned parameters.

=== Establishing a Remote Connection ===
Make sure that the DotNet-Bridge server ("<code>DotNetBridgeServer.exe</code>") is running on the remote system, as explained in the chapter [[#Preparing a remote system for test execuction|"''Preparing a remote system for test execuction''"]]
When the bridge is running, you can connect to it with the "[''Create Remote Connection'']" block using the hostname and IP-Address you specified when you started the bridge.

Notice, that the DotNet-Bridge server only accepts local connections by default.
This is done for security reasons. Use the "-a x.x.x.x" command line argument to specify, which hosts are allowed
to connect. With "-a 0.0.0.0", any host is allowed. Do NOT use this, if the remote host is reachable from untrusted hosts.

=== Closing a Connection ===
Remember to always close a connection when it is no longer needed, as it otherwise needlessly consumes resources.
One simple way to do this is to setup your connection in the "''Before Execution''" (pre-action) part of the test suite or test case,
and put the "[''Close All Connections'']" action block in the "''After exeuction''" (post-action) part.

 

== Accessing GUI Elements ==
[[Bild:WindowsAutomation_Library_AccessBlocks.PNG|frame|The Library's GUI Element Access Blocks.]]
[[Bild:WindowsAutomation_Library_AccessBlocksExamples.PNG|frame|A Few Examples on How to Access Elements in Notepad.]]
[[Bild:WindowsAutomation_Library_AccessBlocksModes.PNG|frame|Different Ways to Reference a GUI Element.]]
All Windows applications are built as a '' tree'' of '' GUI elements''.
Some elements act as container of other element - their children. Tables, for example, are containers
for their cell elements which themselves might contain text labels.
At the root of the tree are one or more ''windows'' . When you connect to an application, you get access to
all windows at the tree's root.
To manipulate any of the system under test's GUI element, you first have to gain access to it.
The group named "''GUI Element Access''" provides action blocks to access elements. The actions are further categorized into sub-groups named "'' Access By XPath''" , "''Access By Property''", "''Existence Test''" etc.
For each category, blocks with the same interface exist. The only difference is the method of retrieval.

;Get GUI Element : returns a ''single'' GUI element matching the search condition. If multiple elements match the condition, an ''arbitrary'' element matching the condition is returned.
:To make sure that there is only one single element matching, set ''ensureExclusive'' to true. You can also enforce this globally by setting the environment variable "''ensureExclusive''" in your environment.
:If ensureExclusive is set and more than one element is found, the block will fail and notify about the ambiguity. This is disabled by default, as checking for uniqueness is a very costly (ie. slow) operation.
:You can also specify a ''timeout'' after which the search is aborted. This is useful if you know an element should be there already (or soon but might currently be loading).

;Get GUI Elements: returns ''all'' GUI elements matching the search condition. If no element is found, it returns an empty list ''Timeout'' and ''cacheXPath'' are also applicable.

;Exists: Works exactly the same as ''Get GUI Element'' but does not fail if no element is found. Additionally provides an output pin specifying if an element has been found.

Both of these blocks are also available in the "''Relative To Anchor''" variety. Those blocks also take a GUI Element as ''anchor'' in relation to which they search.

=== Using XPaths ===

'''XPath''' is the query language used to select GUI elements in the application's element tree.
You can find the XPath of an element with the [[Expecco GUI Tests Extension Reference/en|Gui Browser]] or with third-party applications like "Inspect.exe" [https://msdn.microsoft.com/en-us/library/dd318521(v=vs.85).aspx] or "FlaUInspect" [https://github.com/FlauTech/FlaUInspect].
 As an example, the full ''XPath'' of the scroll button on the
vertical scrollbar in the german Windows "Notepad.exe" application looks like this:

<code>/Window[@Name='Unbenannt - Editor']/Document[@Name='Text-Editor']/ScrollBar[@Name='Vertikale Bildlaufleiste']/Button[@Name='Bildlauf nach unten'] </code>

For each level in the GUI tree, a new ''Location Step'' containing the child element's ''Control Type'' was added in the above XPath.
 You do not have to use any predicates, the following XPath is valid as well:

<code>/Window/Document/ScrollBar/Button </code>

but might lead to issues if multiple GUI Elements match this path.

You can select by three predicates (which can be mixed and matched in the same query):

; Name: the name the application developer has given an element. Be careful as this name might change during programm execution (See for example Notepad's window name which always begins with the name of the currently opened file).
: <code>/Window[@Name='Unbenannt - Editor'] </code>

; AutomationId: An ID the application developer has given an element. It is meant to be unique between siblings but that is not enforced on lazy or incompetent programmers.
: Many lazy developers leave the ID empty or reuse it, making it useless.
: You should use this ID wherever applicable as it is static and meant for this exact purpose.
: <code>/Window/Document[@AutomationId='15'] </code>

;List Index: If there are multiple siblings with the same Control Type, you can select one of them by (1-based) list index.
: <code>/Window[1]/Document[1] </code>
: <code>/Window[1]/Document[last()] </code>

=== Warning there are XPath Limitations ===
'''Please Note''': You can ONLY use the three predicates above in your XPaths.
 Other predicates '''DO NOT''' work!
 To search for an element by another property (e.g. its help text), use the '''By Property''' variant of the block instead.
If the property is not unique, you can select a unique ancestor of the target by property or XPath relative to which the property is unique.
You can then use that ancestor as anchor in the [''Get GUI Element By Property (Relative to Anchor)''] block.

=== Using Wildcards in XPaths ===

XPath also supports '''wildcards'''. You can:
* replace '''one tree level''' with a "*" wildcard:
: <code>/Window/Document[@AutomationId='15']/*/Button[1]</code> 
: <code>/*/*/*/Button[1] </code>

* replace a '''control type''' with a "*" wildcard:
: <code>/Window/*[@AutomationId='15'] </code>

* replace '''an arbitrary amount of levels''' with a "//" wildcard:
: <code>//Button </code> 
: <code>/Window//Button[1] </code>

Especially the last option is useful as it makes your tests more readable, in that the reader can easily focus on the relevant parts of the xpath.

But be careful: using wildcards comes at a steep performance cost (due to the implementation inside the Windows API).
If your test runs unacceptably slow, first try to remove wildcards where they are not needed.

=== Using Properties===

You can also search for elements by property; i.e. by specifying a value an element's property with the given name must have.

For a list of properties a GUI element might have, take a look at Microsoft's documentation [https://docs.microsoft.com/en-us/dotnet/framework/ui-automation/ui-automation-control-patterns-overview#control-pattern-classes-and-interfaces].

=== XPath Resolution in Action Blocks ===

Xpath resolution may be slow in the Windows Automation API, depending on the number of windows/elements which have to be checked.

To speed up test execution, you should reuse a resolved XPath if possible.
For this, use the "Get Element by XPath" action, and feed the "element handle" to multiple actions.
All action- and property access blocks can take either an XPath or an element handle as locator input.

The image on the right shows this mode in action. Variants 1 and 2 are functionally equivalent.
While Variant 2 is more concise, Variant 1 is the right choice in most cases. While it has an additional block, you have control over the other input parameters.
You also can recycle the GUI element reference as seen in 3). This is invaluable as the XPath only has to be resolved once. This speeds up test execution by a lot as XPath resolution is very expensive operation.

'''Rule of thumb''': Always use Variant 1 except if you need the reference to the GUI element only once, or if the application replaces the element dynamically.

=== Separating Path Definitions ===

It is highly recommended to add definitions for element-paths into an environment (typically the project environment), and use "Environment Value" references as input to the steps. This gives two benefits:

* the paths are hidden and the values at the steps become more readable
* your tests are easier to maintain: in case of a changed window layout/structure, only the variable definitions need to be changed at one place.
* you can import those definitions from a CSV or XML file, and thus separate the locators from the actual test suite. In case of changed UI-layout / UI-hierarchy after a revision change of the tested application, all you need is a new excel or xml file containing those definitions.

If the development team of the application can provide the paths of the UI components in a machine readable form (i.e. CVS or XML file), you may even let expecco read and parse those path definitions at test start time, and let it automatically adapt to any change.

 

== Interacting with GUI Elements ==
Once you retrieved a GUI element, you can interact with it by making use of the library's blocks located in the groups '''Elements''', '''Patterns''', and '''Properties'''.
Blocks in those categories take a GUI Element (and sometimes additional data) as input and manipulate it or query for its properties in some way.

[[Bild:WindowsAutomation_Library_ElementsPatternsProperties.png|600px|The Library's Blocks for Interacting With Elements.]]

=== The 'Elements' Group ===

This group contains blocks that are applicable to blocks that only work on GUI elements of a specific type. For a block's detailed description with examples ,
take a look at the block's documentation in expecco.

Even though not only Checkboxes can be 'checked', the [''Check''] block in the "''Checkbox group''" only works for checkboxes and not e.g. for radio buttons.
Because of this limitation there are not that many blocks targeting specific elements. Most blocks target a specific ''pattern'' instead and are therefore in the "''Patterns''" group.

=== The 'Patterns' Group ===

This group contains blocks that are applicable to GUI elements supporting a certain ''pattern''.
Patterns describe how a GUI element ''behaves'' rather than what it ''is''. An element can also support multiple patterns at the same time.
You can find out which patterns an element supports with the [''Get Supported Patterns''] block or by taking a look at Microsoft's documentation about patterns [https://docs.microsoft.com/en-us/dotnet/framework/ui-automation/ui-automation-control-patterns-overview].

Pattern blocks can therefore be ''re-used'' between GUI elements of different types.
For example, the [''Expand''] block in "''ExpandCollapse pattern''", can be used to expand Comboboxes, Menus, Submenus, or Trees.

=== The 'Properties' Group ===

Blocks in the "''Patterns''" and "''Elements''" group already allow you to query the value of properties pertaining to that element or pattern. Blocks in the "''Properties''" group allow you to query both properties which all elements share as well as arbitrary properties. If you try to retrieve a property an element does not support, the block will fail.

Please note that the [''Get Arbitrary Property''] block can only query for properties that belong to a pattern. You cannot, for example, query "Text" from a textfield as this is not a property, use "Value" of the value pattern instead. Microsoft's documentation has a list of patterns and the properties they provide [https://docs.microsoft.com/en-us/dotnet/framework/ui-automation/ui-automation-control-patterns-overview#control-pattern-classes-and-interfaces]

 

== Automating Keyboard and Mouse ==
[[Bild:WindowsAutomation_Library_KeyboardMouse.png|400px|The Library's Blocks for Interacting With Keyboard and Mouse.]]

You can control keyboard and mouse with action blocks in the "''Keyboard''" and "''Mouse''" groups, as shown on the right. In contrast to the blocks above, which work in context of a GUI element, the keyboard and mouse blocks work on a global level. You therefore do not need to provide a GUI element when using them.

You might want to execute some blocks in context of a GUI elemenet nontheless (e.g. enter a number into a text field instead of just pressing keys while the application is running). You can achieve this by selecting the element with the mouse beforehand as you would do when using the application normally (use the [''Left/Double/Right Click On Element''] blocks for this).
If you do not want to wait for the mouse to move, you can also use the [''Set Focus''] block instead.

=== Keyboard ===
The plugin provides blocks to interact with the keyboard on different abstraction levels. The most versatile block is [''Type With Control Keys Pressed''] where you can specify a string of characters to be typed while any number of control keys (e.g. "esc", "alt", "shift", "ctrl", ...) are held down. All other blocks are specializations of this block.

[''Press Control Keys''] e.g. allows you to enter key commands such as renaming files ("ALT+F2"), starting the task manager ("CTRL+ALT+DEL"), or closing a window ("ALT+F4"). [''Press Control Key''] makes it easy to just press a single key (e.g. "RETURN" to start a new line in an edit box). The "''Shortcuts''" group provides an assorted collection of often used key combinations for your convenience.

Use the [''Type''] action to just type some text, or if you just need some throwaway demo text, use [''Type Random Phrase''].

If you need more fine grained control over the keyboard, you can make use of ''Scan Codes''. The keyboard sends a scan code to the operating system whenever a key is pressed or released.
Microsoft provides a list of the scan codes it supports [https://docs.microsoft.com/en-us/previous-versions/visualstudio/visual-studio-6.0/aa299374(v=vs.60)].
[''Press Key By Scan Code''] sends a signal to Windows that a key with a given scan code has been pressed (and is held down). The matching [''Release Key By Scan Code''] sends Windows the adverse signal.
Please note that a key that is pressed, stays pressed until it is explicitly released. If you want to just press and release a key by scan code, use [''Type Key By Scan Code''].

=== Mouse ===
The plugin provides blocks manipulating the mouse in three ways: ''Clicking'', ''Moving'', and interacting with its ''Buttons''.

 

== Recording and Taking Screenshots ==

= Frequently Asked Questions =

== Some elements are not presented in the UI browser's tree ==
This happens if the application "draws" elements (such as checkboxes, buttons or text) without using Windows widgets and without providing proper automation support (btw: which a well behaved application should, because this also affects/prevents usability and makes these controls inaccessable to eg. users with vision disabilities).
We encountered such in table-views containing checkboxes (probably OLE embedded database-tables).
These elements must be addressed either via coordinates (relative to the containing parent element), or via an image search (grab and define the image in the GUI browser). Both have disadvantages and are inconvenient, but there is no other technical solution.

== What is the difference between Click/Invoke/Select/Toggle? ==
Click sends a click event; Invoke calls directly into the application's or widget's event handler; Select and Toggle usually call the corresponding automation functions (if the app-programmer provided that).

A click generates a click event to the widget; may disfunction if the widget is invisible or covered (eg. by a tooltip).

An invoke skips over the event mechanism and calls the event hander directly. It may also not work, if the event handler insists on keyboard focus, mouse position, shift- or ctrl-key or other state.

There exists no mechanism which work with any application: for some, you will have to record a mouse-move and/or a set-focus for the click to work.
If possible, disable tooltips and other automatically appearing popups in the target app.

If none works, try the click at screen position action (which generates a real mouse-click, not via UI-automation to the widget, but via the Windows Event Queue). This should work in any case, but suffers most from popups, mouse position and keyboard focus.

== My element supports a certain pattern but blocks of that pattern don't work ==

== I have designed custom elements, how can I automate them? ==

== I have extended my GUI elements to have custom properties, how can I query them? ==

== Hotkey "Get hovered element" selects the wrong element in the tree ==

Sometimes there are elements which overlap or hide other elements. This element is then selected in the tree. In this case, you can use the Hotkey "Get focused element" to select the element in the tree

== DevExpress controls are not visible in the GUI Browser ==

DevExpress has some possibilities to disable UIAutomation support, which is also used by expecco.If you can't see one or some controls, please check e.g. https://supportcenter.devexpress.com/ticket/details/bc4069/devexpress-controls-now-clear-ui-automation-peers-for-the-application and other information on the DevExpress Support Site.

== Connect fails with "Permission Denied" ==
Some apps required admin access rights to connect to.
You will get a "failed to connect" error and a walkback which looks like:

Could not connect to application: wireguard
System.ComponentModel.Win32Exception (0x80004005): Access denied
bei System.Diagnostics.ProcessManager.OpenProcess(Int32 processId, Int32 access, Boolean throwIfExited)
bei System.Diagnostics.NtProcessManager.GetModuleInfos(Int32 processId, Boolean firstModuleOnly)
bei System.Diagnostics.NtProcessManager.GetFirstModuleInfo(Int32 processId)
bei System.Diagnostics.Process.get_MainModule()
bei FlaUI.Core.WindowsAPI.WindowsApiTools.GetMainModuleFilepath(Process process)
bei FlaUI.Core.Application.Attach(Process process)
bei WindowsAutomation.Application..ctor(String name, UIA3Automation automation, PropertyRepository propertyRepository, String windowTitle)
bei WindowsAutomation.Client.GetApplication(String name, String windowTitle)

You have two options:
* run expecco as admin
* start a dotNet-bridge manually as admin (in the local or remote machine):
...\bridgeFramework\dotNetBridge\dotNetBin>DotNetBridgeServer.exe -k -s -a 0.0.0.0 -p 34319
: then create a "remote connection" to it.

== Execution of GUI Actions blocks after Mouse Down ==
UI Automation is blocking further execution of some blocks after a mouse button <Press>.

== Unable to interact with application (SUT) after Startup ==
In some cases - e.g. starting the test via Jenkins - the application (SUT) is not in the correct state after startup. You can't find elements and/or actions fail.
You can try to send "[WA]Window - Normalize" with the path of the window to solve this

Common Keyboard Shortcuts/en

2026-02-23T11:45:34Z

Sv: Änderung übernommen aus altem Wiki von cg, 13.12.26

In general, keyboard shortcuts perform functions which are also available on popup menus of the individual UI components, and these popup menu are usually context/selection menus. This means, that they typically offer operations on the current selected element within that view. In contrast to eg. Mac OSX, the keyboard shortcuts are context sensitive, and depend on the current focus window. This means that the same shortcut may perform different operations depending on which component has the keyboard focus.

All editing functions can be undone via the "''Undo''" (<kbd>Ctrl-z</kbd>) menu function, in case you pressed the wrong key or inside another component.

Notice that the <kbd>Alt</kbd> key is labelled <kbd>Cmd</kbd> on some keyboards (and also inside the <code>"keyboard.rc"</code> file and the settings dialog.

=== General Editing ===

These shortcuts usually work in any view (i.e. project tree view, diagram- and text editors).
Specific operations are found below.

* '''<kbd>Ctrl-c</kbd>''' - "''Copy''". Copies the selection into the clipboard. The object to be copied depends on the context and selection: - in a text editor, the text-selection is copied. - in the diagram editor, the selected element(s) are copied - in the navigation tree, the selected tree items are copied.

* '''<kbd>Ctrl-v</kbd>''' - "''Paste''" Pastes the clipboard object. This is not always possible, and sometimes simply ignored (for example, if a tree-item is copied and tried to be pasted into a text editor).

* '''<kbd>Ctrl-x</kbd>''' - "''Cut''" Deletes the selection and puts it into the clipboard (for later pasting)

* '''<kbd>Del</kbd>''' - "''Delete''" Deletes but does NOT put the deleted object into the clipboard. In a text editor, the selected text is deleted, or if nothing is selected, the next character (after the cursor) is deleted.

* '''<kbd>Backspace</kbd>''' - "''Delete''" Deletes but does NOT put the deleted object into the clipboard. In a text editor, the selected text is deleted, or if nothing is selected, the previous character (before the cursor) is deleted.

* '''<kbd>Ctrl-z</kbd>''' - "''Undo''" Undoes the last operation. This is a multi-undo. This is the same function as performed by the undo toolbar menu button. This button shows a tooltip, which describes what would be undone if pressed. If you are uncertain, what would be undone, place the mouse over this toolbar button (without pressing) and read the tooltip. Undo for complex operations (tree manipulations, imports etc. are performed via a toolbar button, which shows the kind of operation to be undone in its tooltip).

* '''<kbd>Ctrl-y</kbd>''' - "''Redo''" Undoes the last undo operation. Currently, this works only in text editor windows (i.e. be careful in the diagram editor).

* '''<kbd>Ctrl-f</kbd>''' - "''Find''" Opens a dialog to enter a search string and various options for search (pattern-matching search, wrap at end, etc.). In a text editor, a replace string can be entered for search and replace.

* '''<kbd>F2</kbd>''' - "''Rename''" In the tree or diagram editor, lets you rename the selected element. In a code editor, it renames a variable.

=== Tree/List Organisation ===

The tree interpretes certain shortcuts differently than other views.

* '''<kbd>Ctrl-↓</kbd>''' (= Ctrl-CursorDown) - "''Move Down''" This moves the selected item(s) down in the navigation tree or a testplan's list of test cases. In a diagram editor, if a step's pin is selected in the diagram editor, this is moved towards the bottom.

* '''<kbd>Ctrl-↑</kbd>''' (= Ctrl-CursorUp) - "''Move Up''" This moves the selected item up in the navigation tree or a testplan's list of test cases. In a diagram editor, if a step's pin is selected in the diagram editor, this is moved towards the top.

* '''<kbd>Ctrl-←</kbd>''' (= Ctrl-CursorLeft) - "''Move Out''" In the navigation tree, this moves the selected item out of its containing (parent) item and places it below the parent in the list.

* '''<kbd>Ctrl-→</kbd>''' (= Ctrl-CursorRight) - "''Move In''" In the navigation tree, this moves the selected item into the tree item right above it. I.e. it makes it a child element of the other item.

* '''<kbd>Ctrl-Shift-↓</kbd>''' (= Ctrl-Shift-CursorDown) - "''Move to Bottom''" This moves the selected item(s) down in the navigation tree to the end of the children list.

* '''<kbd>Ctrl-Shift-↑</kbd>''' (= Ctrl-Shift-CursorUp] - "''Move to Top''" This moves the selected item up in the navigation tree to the beginning of the children list.

=== Element Creation (Diagram Editor) ===

* '''<kbd>Ctrl-n</kbd>''' - "''New Step''" In the diagram editor: opens a dialog to create a new step. The dialog lets you choose the action which is to be instantiated. If a pin is selected, the dialog filters are preset to only show action blocks with correspondingly typed pins. In the scheme editor: adds a new input or output pin, depending on the currently selected pin's type.

* '''<kbd>Ctrl-r</kbd>''' - "''Replace''" In the diagram editor, this opens a dialog to choose another action which is to replace the selected action.

* '''<kbd>Ctrl-g</kbd>''' - "''Graphic''" In the diagram editor, this opens a dialog to choose an image which is added as annotation (useful to mark areas of the diagram as "Under Construction" or "Attention Here".

* '''<kbd>Ctrl-i</kbd>''' - "''New InputPin''". In the scheme editor, this adds a new input pin - same as clicking on the "''Add Input Pin''" button.

* '''<kbd>Ctrl-o</kbd>''' - "''New OutputPin''". In the scheme editor, this adds a new output pin - same as clicking on the "''Add Output Pin''" button.

More editing functions are found in every text editor's, lists or diagram's right-button menu; some of which do have keyboard shortcuts.

=== Code Editor ===

For a full list, see [[Code_Editor/en#Editor_Functions_and_Keyboard_Shortcuts|"Editor Functions and Keyboard Shortcuts"]].

* '''<kbd>Ctrl-g</kbd>''' - "''Goto Line''" In text editors: to position the cursor to an entered line number. If the entered number has a sign (+/-), the positioning is relative to the current line. In a diagram editor, a graphic annotation is inserted (see below)

* '''<kbd>Alt-f</kbd>''' - "''Forward Search''" Searches for the next occurrence of the previous search string.

* '''<kbd>Alt-b</kbd>''' - "''Backward Search''" Searches for the previous occurrence of the previous search string.

* '''<kbd>F8</kbd>''' - "''Again''" Repeats the last cut or replace operation in a text editor. For example, to replace a string by another string, first select it, type in the new word, then press <kbd>F8</kbd> to search for the next occurrence and replace again. If the previous operation was a "cut" or "delete", then <kbd>F8</kbd> searches for the next occurrence and deletes that again.

* '''<kbd>F4</kbd>''' - "''Comment''" In an elementary code editor, comments the selection or the current cursor line

* '''<kbd>F5</kbd>''' - "''Uncomment''" In an elementary code editor, uncomments the selection or the current cursor line

* '''<kbd>F6</kbd>''' - "''Toggle Case''" toggles the selection between titlecase, uppercase and lowercase (press multiple times)

* '''<kbd>F9</kbd>''' - "''Undent by 4''" remove the left 4 spaces of the selected line range, or the cursor line (if no lines are seleted). Undent is also possible by selecting a number of lines and pressing <kbd>Shift-Tab</kbd>.

* '''<kbd>F10</kbd>''' - "''Indent by 4''" add 4 spaces to the left of the selected line range, or the cursor line. Indent is also possible by selecting a number of lines and pressing <kbd>Tab</kbd>.

* '''<kbd>F11</kbd>''' - "''Undent by 1''"

* '''<kbd>F12</kbd>''' - "''Indent by 1''"

* '''<kbd>Ctrl-d;</kbd>''' - "''DoIt''" This works in code editors for Smalltalk or the builtin JavaScript actions. It takes the currently selected piece of text and immediately executes it as a program. The result is silently discarded (see below for more). If no text is currently selected, the current cursor line is taken as input. See the "[[Smalltalk Syntax Cheat Sheet]]" for a short syntax summary.

* '''<kbd>Ctrl-p;</kbd>''' - "''PrintIt''" Simular to the above, but the result is pasted after the selection. As an example, in a code editor, type "<code>45 degrees sin</code>" (without the double quotes), select it, and press <kbd>PrintIt</kbd>. The result will be pasted after the selection. This also works in a workspace/notepad window.

* '''<kbd>Ctrl-q;</kbd>''' - "''InspectIt''" Simular to the above, but an inspector window is opened on the result.

* '''<kbd>Ctrl-B;</kbd>''' (Ctrl-Shift-B) - "''BrowseIt''" Simular to the above, but a class browser is opened on the result's class, showing all operations (methods) which are implemented by this object.

* '''<kbd>Ctrl-I;</kbd>''' (Ctrl-Shift-I) - "''Implementors''" Extracts a Smalltalk message name (i.e. the name of an operation) and opens a browser on all methods in the system which implement that message.

=== Other ===

* '''<kbd>Ctrl-+</kbd>''' (= Ctrl-plus) - "''Zoom In''" Text in the current focus view is shown in a larger font; diagrams are magnified

* '''<kbd>Ctrl--</kbd>''' (= Ctrl-minus) - "''Zoom Out''" Text in the current focus view is shown in a smaller font; diagrams are shrunk

* '''<kbd>Ctrl-Shift-+</kbd>''' (= Ctrl-Shift-plus) - "''Zoom In All''" Zoom-In all components of the expecco window

* '''<kbd>Ctrl-Shift--</kbd>''' (= Ctrl-Shift-minus) - "''Zoom Out All''" Zoom-Out all components of the expecco window.

=== Customizing Keyboard Shortcuts ===

When expecco starts, it looks for a file named "<code>keyboard.rc</code>" in the "<code>bin</code>" folder (where the expecco executable is installed). All keyboard shortcuts are defined in this script file. To customize the keyboard shortcuts, take the code there as a guide.

These definitions are the default settings; however, individual users may as well change or add personal preferences
via the "''Extras''" → "''Settings''" → "''Keyboard''" dialog.

Release Notes 26.x

2026-02-23T11:41:53Z

Sv: Änderung übernommen aus altem Wiki von cg, 14.1.26

See also: [[Release Notes 25.x]]
 

== Release 26.2 ==

== Release 26.1 ==
*Feature: Qt-Plugin supports Qt6.8 ([[QT_Testing/en#ExpeccoTestService_Library%3A_Delivery_in_Expecco_Versions|Delivered versions for QT and build environment]])
* Feature: improved search text box behavior in text editors (type RETURN, CMD-f or CMD-b while box is open) and back to original position button added.

Expecco API/en

2026-02-23T11:38:55Z

Sv: Änderung übernommen aus altem Wiki von cg, 18.12.25

== How to Program ==

Before you start programming, please read the [[How_to_Program/en | "How to Program"]] document, which describes how program code is handled in expecco.
Unless you are familiar with the dynamics of a Smalltalk development environment, some of it may be unknown to you, and you will have more fun and be more productive, if you know the power of the tools. For the best development experience, take a look at the debugger, workspace (notepad) and data inspectors.

The rest of this document describes the syntax and semantics of the elementary action languages. For tool usage, please read the [[How_to_Program/en | HowTo]] document.

== expecco API ==

The expecco API provides functions and access to the underlying class library for the use in [[Elementary Block|elementary blocks]] written in Smalltalk and JavaScript (i.e. for code which is executed inside expecco itself). This API is not available for elementary blocks written in other languages which are executed by external script engines (Shell, Batch, Python, Node.js etc.) or inside a different Java or CLR Virtual Machine (Groovy, VBScript, IronPython). However, a subset of the functions are supported as RPC (remote procedure calls) in bridged elementary actions.

For a short introduction to the Smalltalk programming language,
please read the [http://live.exept.de/doc/online/english/getstart/tut_2.html Smalltalk tutorial in the Smalltalk/X online manual].
For a full book on learning Smalltalk, read [http://live.exept.de/doc/books/JoyOfST/JoyOfST.pdf "The joy of Smalltalk, An introduction to Smalltalk" by Ivan Tomek].

The [[#Groovy Elementary Blocks|API for Groovy elementary blocks]] is different and described below.
 The API for bridged Node.js actions is described [[#Node.js_.28Bridged.29_Elementary_Blocks|here]].
 The API for bridged Python and Jython actions is described [[#Bridged Python Elementary Blocks|here]].
 The API for bridged Ruby actions is described [[#Bridged Ruby Elementary Blocks|here]].
 The API for bridged C actions is described [[#Bridged C Elementary Blocks|here]].

==JavaScript and Smalltalk Elementary Blocks ==

The expecco JavaScript and the Smalltalk API consist of the same functions - both call into the underlying [http://www.smalltalk-x.de Smalltalk/X] system, for which extensive documentation is available as
[http://live.exept.de/doc/online/english/TOP.html Online Documentation] and
as [http://live.exept.de/ClassDoc Class Reference].

The Smalltalk/X language and class library are [http://wiki.squeak.org/squeak/uploads/172/standard_v1_9-indexed.pdf ANSI compatible]; therefore the official ANSI documents, Smalltalk literature and tutorials are also valuable sources of information (for example, the online tutorials you may find in youtube).

:- If you wonder "why Smalltalk?", you should know that [https://insights.stackoverflow.com/survey/2017#most-loved-dreaded-and-wanted Smalltalk ranked nr. 2 in a 2017 survey of "most loved languages"] - admittedly, this ranking may be subjective (in that Smalltalk programmers might be more loyal), but it should at least raise your eyebrows.
:- It is not among the most used languages - but that decision is usually made by people who do not even know Smalltalk or who think that language does not matter.
:- If you think it is outdated, be reminded that Smalltalk has the most consistent object model and reflection facilities of all OO languages, and that modern clones like Ruby and Python only provide a subset of Smalltalk's facilities. If you don't know it, don't judge it.
:- The underlying virtual machine (VM) is feature rich and provides many mechanisms which are not possible in most 'modern' languages. For example, in most (if not all) of the current languages it is not possible to interrupt a thread which blocks in a system call (eg. in a read). In none of them, are exceptions proceedable. In none of them can you interrupt other threads in any situation (again: especially not if it is inside a blocking read).
:- The set of integrated tools is massive in Smalltalk: full access to classes, threads, semaphores, any object's internals are all provided by graphical tools which can be opened by double clicks or via menus.

Expecco's JavaScript is implemented by compiling JavaScript syntax to the underlying Smalltalk bytecode. It is not fully compatible with a "real" JavaScript: it is class based, and the underlying object model and class library are actually the Smalltalk/X object model and class library. Thus, expecco's JavaScript can be seen as "a Smalltalk with JavaScript syntax".

Please be not confused by two JavaScript-based elementary actions: the builtin JavaScript described here is executed within expecco itself whereas Node-actions are executed in a separate Node.js virtual machine. These Node actions are "real JavaScript" and are described in a separate [[#Node.js_.28Bridged.29_Elementary_Blocks |chapter below]].

===Smalltalk / JavaScript Short Syntax Overview===
Expecco's builtin JavaScript and Smalltalk only differ in their syntax - semantically they are very similar:
{| class="wikitable"
! JavaScript
! Smalltalk
!
|-
|style="width: 15em"|this
|style="width: 15em"|self
| the current activity (inside an elementary action)
|-
|this.functionName()
|self functionName
| a call without arguments
|-
|this.''functionName''(''arg'')
|self ''functionName'':''arg''
| a call with one argument
|-
|this.''namePart1_part2''(''arg1'',''arg2'')
|self ''namePart1'':''arg1'' ''part2'':''arg2''
| two arguments Notice that in Smalltalk, the arguments are ''sliced'' into the name parts, and that the concatenation of the parts is the actual name (incl. the colons). Thus, in "<code>x at:5 put:10</code>" the name of the called method is "at:put:" and it gets two arguments: 5 and 10. Whereas "<code>(x at:5) put:10</code>" would first send an "at:" message, then send a"put:" message to the object returned from "at:". In JavaScript, ":" is not a valid character in a function name, and a translation mechanism is applied which replaces ":" by underline, and drops the final colon.
|-
| ''functionName''(...)
| self ''functionName''...
| implicit ''this'' receiver in JS explicit in Smalltalk
|-
| ''accessor''
| self ''accessor''
| slot access - implicit this receiver in JS explicit in Smalltalk
|-
| ''stat1'' ; ''stat2'' ;
| ''stat1'' . ''stat2''
| statement terminator / separator in ST: to '''separate''' statements in JS: to '''terminate''' a statement. In Smalltalk, the last period "." inside a method or block can be and often is omitted.
|-
| if (''cond'') {     ''ifStats'' } else {     ''elseStats'' }
| ''cond'' ifTrue:[     ''ifStats'' ] ifFalse:[     ''elseStats'' ]
| conditional execution. Notice the square brackets in Smalltalk
|-
| while (''cond'') {     ''stats'' }
| [ ''cond'' ] whileTrue:[     ''stats'' ]
| while-loop. Notice the brackets around the condition in Smalltalk
|-
| for (i=''start''; i<=''end''; i++) {     ''stats using i'' }
| ''start'' to:''end'' do:[:i |     ''stats using i'' ]
| counting-loop. Seldom used in Smalltalk
|-
| foreach (''el'' in ''collection'') {     ''stats using el'' }
| ''collection'' do:[:el |     ''stats using el'' ]
| loop over collection elements. Very often used in Smalltalk
|-
| function () { ''stats'' }
| [ ''stats'' ]
| an anonymous (inner) function (called "block" in ST). JS: return value via explicit return ST: return value is last expression's value
|-
| function (''a1'', ''a2'',...) { ''stats'' }
| [:''a1'' :''a2'' ...| ''stats'' ]
| in ST: blocks are references to anonymous function
|-
| var ''v1'', ''v2'', ... ;
| | ''v1'' ''v2'' ... |
| local variables inside a function (or block). Semantically, these are "let" variables (i.e. only seen in the current scope)
|-
| return ''expr'';
| ^ ''expr''
| return a value. In ST: a return from within a block returns the enclosing '''top-level''' method In JS: a return returns from the '''inner''' function
|-
|
| '...'
| String constant without c-escapes
|-
| "..." or '...'
| c'...'
| String constant with c-escapes (\n, \t, etc.)
|-
| `...${ expr1 } .. ${ expr2 } ...`
| e'..{ expr1 } .. { expr2 } ...'
| String with sliced in expressions (exprs will be converted to string). Also known as ''TemplateStrings''.
|-
| 0xXXX, 0bXXX, 0XXX
| 0xXXX, 0bXXX, 0oXXX or 16rXXX, 2rXXX, 8rXXX (notice: 0177 is a decimal in Smalltalk, but octal in JS)
| Integer constants (hex, binary, octal)
|-
|
| #(el1 ... el2)
| literal (constant) array constructed at compile time. Notice that elements are separated by spaces
|-
| [ex1 , ex2 , ... , exN]
| {ex1 . ex2 . ... . exN}
| literal (constant) array constructed at execution time. Notice that in Smalltalk, expressions are separated by periods (must be, because "," is an operator to concatenate collections)
|-
| /* ... */
| " ... "
| comment
|-
| // ...
| "/ ...
| end of line comment
|-
|
| "<<TOKEN ... TOKEN
| token comment
|}

==== Smalltalk Operator Precedence ====
Smalltalk beginners may be irritated by the missing binary operator precedence rules: in Smalltalk, all operators have the same precedence and are evaluated left to right. Thus if you write:
a + b * 5
the JavaScript semantic is:
a + (b * 5)
whereas in Smalltalk, it is evaluated as:
(a + b) * 5
(i.e. left to right).

Therefore, as a guideline (and actually a good convention), all Smalltalk binary expressions with more than one operator should be parenthesized to make the intention clear. It make clear that it is intended, that should be done even if the left-to-right order matches the mathematical precedences.

==== Smalltalk Operators ====
Another uncommon feature of the Smalltalk language is that there are only 6 keywords in the language
("<code>self</code>", "<code>super</code>", "<code>true</code>", "<code>false</code>", "<code>nil</code>" and "<code>thisContext</code>").
 Every other word is either the name of a variable or the name of a message to be sent to an object (aka a "''virtual function call''" or "''method invocation''").

Every sequence of special characters (except "<code>:</code>" (colon), "<code>.</code>" (period), "<code>(</code>" (left), "<code>)</code>" (right parenthesis), "<code>[</code>" (left), "<code>]</code>" (right bracket), <code>{</code>" (left),<code>}</code>" (right brace), "<code>:=</code>" (assign), "<code>^</code>" (return) and "<code>;</code>" (semicolon) ) is interpreted as operator (or in other words: as the name of a message/virtual function call).

Thus, the sequences "<code>-></code>", "<code>=</code>", "<code>=></code>", "<code><-</code>" and especially the comma ("<code>,</code>") are operators which are treated like "<code>+</code>", "<code>-</code>" etc.

Finally, message sends ("''function calls''") with arguments are always written with keyword arguments. I.e. the arguments are prefixed by a keyword (which is an identifier with a colon). Smalltalk does not allow positional arguments in a message send.

==== Calling Functions and Invoking Methods (aka "Sending Messages") ====
All functions are actually implemented in Smalltalk and follow the standard Smalltalk naming conventions. The same function names are used for JavaScript. As seen above, this scheme works well for functions without or with a single argument, but requires a name translation for functions with more than one argument. This translation is done by the JavaScript compiler by replacing every colon (:) of the Smalltalk name by an underline (_) character, except for the last colon if there are more than one. Thus for example, the Smalltalk name "<code>at:put:</code>" will be named "<code>at_put</code>" in JavaScript.

In JavaScript, a function-name alone (i.e. without explicit receiver) is translated into a self-send; thus "<code>this.foo()</code>" and "<code>foo()</code>" are equivalent.



For example, the JavaScript call:
this.'''environmentAt'''("foo")
is written in Smalltalk as:
self '''environmentAt:''''foo'

and, to demonstrate the multi-argument translation rule, the Smalltalk code:
self '''environmentAt:''''foo' '''put:'''1234
is written in JavaScript as:
this.'''environmentAt_put'''("foo", 1234)
or (because of the implicit receiver being "this"), alternatively:
'''environmentAt_put'''("foo", 1234)

=== Syntax Summary ===
For a formal specification of the JavaScript and Smalltalk languages, see the appendixes below.
The following gives a rough overview over the most common syntactic constructs.

{| class="wikitable"
! JavaScript
! Smalltalk
! Notes
|-
|style="width: 10em"| this
|style="width: 10em"| self
| the current activity
|-
| null
| nil
| a null reference (UndefinedObject)
|-
| ;
| .
| statement terminator/separator In JavaScript it is a terminator, meaning that every statement (except brace-blocks) must be terminated by a semicolon. In Smalltalk, it is a separator, meaning that the last statement in a block or method does not need one.
|-
| "..."
| '...'
| a String constant (JavaScript allows single quotes too); no C-escapes in Smalltalk
|-
|
| c'...'
| a Smalltalk String constant with c-escapes
|-
|
| e'..{ expr } ..'
| a Smalltalk String with embedded expressions (sliced-in)
|-
|
| #'...'
| a Symbol constant (not available in JavaScript; use "xxx".asSymbol() in JS)
|-
|
| #...
| also a Symbol constant (not available in JavaScript; use "xxx".asSymbol() in JS)
|-
| [ el1 , el2 , ... ]
| #( el1 el2 ... )
| an Array constant (elements must be constant literals) Notice the separating comma in JS, but space-separated elements in Smalltalk. In Smalltalk, the array is created at compile time (i.e. runtime cost is zero); the array is immutable, whereas in JS it is created mutable at runtime
|-
| [ expr1 , expr2 , ... ]
| { expr1 . expr2 . ... }
| a computed Array (elements are expressions) notice the expression terminators in ST (periods), and that "," (comma) is an operator in ST. The array is created at runtime; the array is mutable
|-
|
| #[ el1 el2 ... ]
| an immutable ByteArray constant (not available in JavaScript)
|-
| 1234
| 1234
| an Integer constant (arbitrary precision)
|-
| 0x1234
| 0x1234 or 16r1234
| a hexadecimal Integer constant (radix is 16) (arbitrary precision)
|-
| 0b10001010
| 0b10001010 or 2r10001010
| a binary Integer constant (radix is 2) (arbitrary precision)
|-
| 0177
| 8r177
| an octal Integer constant (radix is 8) (arbitrary precision)
|-
|
| 3r10001010
| a ternary Integer constant (radix is 3); not available in JavaScript
|-
|
| <N>rxxxx
| an N-ary Integer constant (radix is N); not available in JavaScript
|-
|
| ( num / den )
| a Fraction constant (not available in JavaScript); both numerator and denominator must be integers
|-
| 1.234 1e5
| 1.234 1e5
| Floating Point constants (double precision)
|-
| v = expression
| v := expression
| assignment to a variable
|-
| expr1 == expr2
| expr1 = expr2
| compare for equal value
|-
| expr1 === expr2
| expr1 == expr2
| compare for identity be careful: 1.0 (the float) is NOT identical to 1 (the integer) However, they are equal in value.
|-
| rcvr.f ()
| rcvr f
| function call (always a "virtual function call")
|-
| rcvr.f (arg)
| rcvr f: arg
| with 1 arg
|-
| rcvr.a_b (arg1, arg2)
| rcvr a: arg1 b: arg2
| with args notice the different names of the function "a_b" vs."a:b:"
|-
| return;
| ^ self
| without return value ST: from enclosing method; JS: from current function
|-
| return expr;
| ^ expr
| with return value ST: from enclosing method; JS: from current function
|-
| return from execute;
| ^ self
| return from execute activity from within an inner function
|-
| ! expr
| expr not
|
|-
| e1 && e2
| (e1 and:[ e2 ])
| non evaluating and (e2 is not evaluated if e1 is false)
|-
| e1 || e2
| (e1 or:[ e2 ])
| non evaluating or (e2 is not evaluated if e1 is true)
|-
|
| pin <- value
| only for output pins: writes value to the pin (same as "pin value(val)")
|}

=== Syntactic Sugar ===

Some syntactic constructs of the JavaScript language are implemented as library functions in Smalltalk. Among others, most noteworthy are conditional execution (if-the-else) and loops.

Non-Smalltalkers should be aware that in Smalltalk all control structures are implemented as library functions (i.e. method invocations) to corresponding receiver objects. They get a block (=closure or anonymous function) as argument, which is then possibly evaluated. The Smalltalk block syntax "<code>[...]</code>" makes this extremely convenient and easy to use.

It is the responsibility of the Smalltalk compiler and runtime system, to care for optimized execution of such code (typically by inlining the code). However, it is still possible to put a block into a variable, to pass it as argument, or to return it as value from a method or block. Thus, in Smalltalk, variables or computed blocks may also be used as arguments to messages like "<code>ifTrue:</code>", "<code>whileTrue:</code>", "<code>do:</code>" etc.

 The JavaScript syntax for control structures is mapped to corresponding Smalltalk library functions as follows:
{| class="wikitable"
! JavaScript
! Smalltalk
! Notes
|
|-
|style="width: 15em"|if (''expr'') { ... }
|style="width: 15em"| (''expr'') ifTrue:[ ... ]
| Notice the square brackets
|-
|if (! ''expr'') { ... }
| (''expr'') ifFalse:[ ... ]
|
|-
| if (''expr'') { ... } else { ... }
| (''expr'') ifTrue:[ ... ] ifFalse:[ ... ]
|
|-
| if (!''expr'') { .. } else { ... }
| (''expr'') ifFalse:[ ... ] ifTrue:[ ... ]
|
|-
| while (''expr'') { .. }
| [''expr''] whileTrue:[ ... ]
| Notice the square brackets around the condition
|-
| for (''expr1'';''expr2'';''expr3'') { .. }
| ''expr1''. [''expr2''] whileTrue:[ ... . ''expr3'' ]
|
|-
| for (var i=''start''; i<=''stop''; i++) { .. }
| ''start'' to:''stop'' do:[:i | ... ]
|
|-
| for (var i=''start''; i<=''stop''; i+=''incr'') { .. }
| ''start'' to:''stop'' by:''incr'' do:[:i | ... ]
|
|-
| try { .. } finally { ... }
| [ ... ] ensure:[ ... ]
|
|-
| try { .. } catch(e) { ... }
| [ ... ] on:Error do:[:e | ... ]
|
|-
| try { .. } catch(e) { ... } finally { ... }
| [ ... ] on:Error do:[:e | ... ] ensure:[ ... ]
|
|-
| ''var''++
| ''var'' := ''var'' + 1
|
|-
| ''var''--
| ''var'' := ''var'' - 1
|
|-
| ''arr''[ ''idx'' ]
| ''arr'' at:''idx'' ''arr''[ ''idx'' ]
| Array and Dictionary indexed fetch Notice that real JavaScript uses 0-based indexing, whereas Smalltalk and expecco JavaScript is 1-based. Smalltalk/X also allows the bracket notation for indexed access.
|-
| ''arr''[ ''idx'' ] = ''expr''
| ''arr'' at:''idx'' put:''expr'' ''arr''[ ''idx'' ] := ''expr''
| Array and Dictionary indexed store Smalltalk/X also allows the bracket notation for indexed access.
|}

=== Operators ===
{| Border
! JavaScript
! Smalltalk
! Notes
|-
| %
| \\ %
| modulu operator
|-
| <<
| leftShift:
| left-shift negative shift count is right-shift
|-
| >>
| rightShift:
| right-shift negative shift count is left-shift
|-
|
| bitShift:
| left or right shift; negative shift count is right-shift positive is left shift (not available in JavaScript)
|}

More details are in the [[Smalltalk Syntax Cheat Sheet]].

=== Array Indexing ===

A big potential pitfall is the different indexing base used in Smalltalk vs. (standard) JavaScript: in Smalltalk, array indices start at 1 and end at the array's size. In (standard) JavaScript, indices start at 0 and end at the array's size minus 1.

This also affects some character- and substring search functions, which return 0 (zero) in Smalltalk, whereas some of the standard JavaScript functions return -1 if nothing is found.

The following functions expect or return 0-based indices if used in JavaScript:
* ''collection''.<code>'''indexOf:'''</code>(''element'') attention: there exists a corresponding Smalltalk method, which returns a 1-based index
* ''collection''.<code>'''lastIndexOf:'''</code>(''element'') attention: there exists a corresponding Smalltalk method, which returns a 1-based index

* ''collection''.<code>'''indexOf:'''</code>(''element'', ''startIndex'') the corresponding Smalltalk method "<code>indexOf:</code>''element'' <code>startingAt:</code>''startIndex''" uses 1-based indices
* ''collection''.<code>'''lastIndexOf:'''</code>(''element'', ''startIndex'') ditto

We admit that this is a little confusing at times, but there is no easy solution to this: and we decided to neither change the Smalltalk nor the JavaScript scripting languages inside expecco.

To make your intentions explicit, you can use variants of the "<code>indexOf"/"lastIndexOf</code>" functions which make these implicit differences more explicit: "<code>indexOf0()</code>" / "<code>lastIndexOf0()</code>" and "<code>indexOf1()</code>" / "<code>lastIndexOf1()</code>" are available for both languages.

Shame on us: 
the above array indexing behavior was changed for <code>indexOf:</code> between 2.7 and 2.8 (due to a missing translation, the 2.7 versions used 1-based indices in both languages).
This leads to a problem, if you run any old 2.7 suite in newer expecco versions without reimporting the StandardLibrary or if you used those functions in your own elementary code.
To avoid a need to touch those old suites, we have added a backward-bug-compatibility mode, which is described in a separate note of the release notes.

=== Inner Functions ===
==== Inner Functions in JavaScript ====

It is possible to create functions within the elementary block's code. This example shows how to do so:
execute() {
...
function f(arg1, arg2) {
return(arg1 + arg2);
}
...
}
An inner function "f" is created with two arguments ("arg1" and "arg2"), which returns the sum of both. The function is called like this:
f(3,5)
Inner functions can be used for example to filter specific elements from collections, as in:
function isEven(n) { return n.even(); }

var numbers = [1,2,3,4,5,6,7];
var evenNumbers = numbers.select( isEven );

Inner functions are '''first class objects''': they can be stored in variables, collections, passed as argument or returned from functions. They can even be passed to other blocks via input- and output pins or via environment variables. Functions can be anonymous; the above example could also be written as:
execute() {
var f;
...
f = function (arg1, arg2) {
return(arg1 + arg2);
}
...
}
(notice the missing function name after the "function" keyword).

Notice, that there is a difference in the behavior of the return statement between JavaScript inner functions and Smalltalk blocks:
a JavaScript "return" statement inside an inner function returns from that inner function only, whereas a return in Smalltalk always returns from the outer-most method.

To return from the outermost function in JavaScript, use the "<CODE>return from <''fnName''></CODE>" statement form.

In expecco, where the outermost function is always named "''execute''", write:
execute() {
...
function myFunction() {
...
return from execute;
}
...
}
(notice that the execute function is not supposed to return a value)

===== Lambda Expressions in JavaScript =====

JavaScript functions can also be written in a slightly shorter lambda notation as:
(arg1, ... argN) => { statement; ... return expression; }
or (with a single argument) as:
arg => { statement; ... return expression; }
or (without arguments) as:
() => { statement; ... return expression; }
and results in a function object comparable to:
function (arg1, ... argN) { statement; ... return expression; }

The function's body may also be a single expression (without braces), as:
arg => expression
For example:
aCollection.map( el => el ** 2 )
returns a collection of squared numbers,
the same as the corresponding Smalltalk code:
aCollection map:[:el | el ** 2 ]
This is plain "syntactic sugar" - it does not give any new semantic functionality, but makes the code shorter and possibly easier to read.

==== Inner Functions in Smalltalk (Blocks) ====

In Smalltalk, inner functions are called "''block''", and are defined as:
f := [:arg1 :arg2 | arg1 + arg2 ].
This block can be called by sending at a "<code>value:value:</code>" message (i.e. one "<code>value:</code>" for each argument) (1):
f value:3 value:5
or by passing an array of argument values with "<code>valueWithArguments:</code>" as in:
args := #(3 5). "/ an array constant
f valueWithArguments:args
or:
args := { 3 . 5 }. "/ a computed array
f valueWithArguments:args

The returned value is the value of the last expression inside the block. Thus, blocks can contain multiple expressions separated by a period:
f := [:arg1 :arg2 |
Transcript showCR: e'my first arg is: {arg1}'.
Transcript showCR: e'my second arg is: {arg2}'.
arg1 + arg2 "/ the block's return value
].
This is in contrast to a JavaScript inner function, where an explicit "return" statement is needed. The return value of JavaScript inner function without an explicit return will be void.
Therefore, the above inner function in JavaScript has to have a return:
f = function(arg1, arg2) {
Transcript.showCR('my first arg is: '+arg1);
Transcript showCR('my second arg is: '+arg2);
return (arg1 + arg2); // the function's return value
};

Blocks without argument are defined as:
f := [ Transcript showCR:'blabla: Euler was great' ].
and invoked with a simple "<code>value</code>" message.

In both JavaScript and Smalltalk code, it is an error to invoke an inner function/block with a wrong number of arguments (2).

Smalltalk blocks and JavaScript inner functions can be used interchangeable - i.e. it is possible to pass a JS inner function to a collection method such as "<code>collect:</code>" or "<code>select:</code>". It is also possible, to pass either via input/output pins to other activities (which is not considered good style, as it could make the program quite hard to understand, if not used with caution).

Notice again, that the behavior of the Smalltalk return ("^") is different from a JavaScript return ("''return-Statement''") inside inner functions. The JavaScript return returns a value from the inner function, whereas the Smalltalk return forces a return from the containing method (the block's "execute" method). The Smalltalk return always behaves like the "return from execute" JavaScript special form.

1) Smalltalk/X allows for a non-standard block evaluation message using the "normal" parentheses notation. I.e. you can call a block with its arguments in parentheses as in "<code>f(1, 2, 3)</code>. This is syntactic sugar for the standard <code>f value:1 value:2 value:3</code>.

2) in Smalltalk, you can define "''varargs blocks''" with the "<code>asVarArgBlock</code>" message. The block will then receive its arguments as a vector, and fetch them using collection protocol (i.e. "size", "at:" or enumeration messages like "do:"). For example,
b := [:args | Transcript showCR: e'my arguments are {args}' ] asVarArgBlock
can be called with any number of arguments.

==== Example uses for Inner Functions ====

In Smalltalk, blocks are very often used when enumerating collections.
 For example, code corresponding to a C# 3.0 collection "<code>select (where(x => ...))</code>" is written in Smalltalk as:
|names namesStartingWithA|

names := #( 'Alice' 'Ann' 'Bob' 'Mallory' ).
namesStartingWithA := names select:[:n | n startsWith:'A'].

or in JavaSript as:
var names, namesStartingWithA;

names = [ "Alice" , "Ann" , "Bob" , "Mallory" ];
namesStartingWithA = names.select( function(n) { n.startsWith("A"); } );
or alternative using lambda expressions as:
var names, namesStartingWithA;

names = [ "Alice" , "Ann" , "Bob" , "Mallory" ];
namesStartingWithA = names.select( n => n.startsWith("A") );

To find the first element in a collection, for which some condition is true, use:
|names firstNameContainingAnO|

names := #( 'Alice' 'Ann' 'Bob' 'Mallory' ).
firstNameContainingAnO:= names detect:[:n | n includesString:'o'].

or in JavaSript as:
var names, firstNameContainingAnO;

names = [ "Alice" , "Ann" , "Bob" , "Mallory" ];
firstNameContainingAnO = names.detect( function(n) { n.includesString("o"); } );

For more information on the Smalltalk syntax, see [[http://live.exept.de/doc/online/english/getstart/tut_2.html Smalltalk Basics]] in the [[http://live.exept.de/doc/online/english/getstart/tutorial.html Smalltalk Online Tutorial]].

=== Builtin Data Types ===

The builtin types below and user defined primary types are mapped to corresponding classes of the underlying Smalltalk runtime system.
An introductory overview and links to the detailed documentation of individual classes is found in the
[http://live.exept.de/doc/online/english/classDoc/TOP.html Smalltalk Class Documentation] of the [http://live.exept.de/doc/online/english/TOP.html Smalltalk/X online documentation]. The following gives a rough summary of the main concepts. A good entry point for further learning is the [http://live.exept.de/doc/online/english/overview/basicClasses/TOP.html Smalltalk/X Basic Classes Overview Document], which provides links to the most heavily used classes and more detailed information.

==== Numeric Types ====

The underlying numeric type implementation supports multiple number representations. These can be used transparently in mixed-operations, and values are automatically converted as required. For example, the division of two integers returns another integer iff the division does not produce a remainder. Otherwise, a fraction object is returned.
Although very very rarely required in practice,
values can be converted explicitly, via one of the "<code>asXXX</code>" messages:
* <code>asFloat64()</code> - to convert to a double precision IEEE 64bit float
* <code>asFloat32()</code> - to convert to a single precision IEEE 32bit float
* <code>asFloat80()</code> - to convert to an extended precision IEEE 80bit float
* <code>asFloat128()</code> - to convert to an extended precision IEEE 128bit float
* <code>asInteger()</code>
* <code>asFraction()</code>
* <code>asScaledDecimal(scale)</code>
the older API is still supported, but less self explanatory:
* <code>asFloat()</code> - to convert to a double precision IEEE 64bit float
* <code>asShortFloat()</code> - to convert to a single precision IEEE 32bit float
* <code>asLongFloat()</code> - to convert to an extended precision IEEE 80bit float

Thus, if you want to avoid fractions (why would you?), process the result of an integer division using one of the <code>asFloat()</code>, <code>truncated()</code>, <code>floor()</code>, <code>ceiling()</code> or <code>rounded()</code> functions. But be aware that fractions provide an exact result, whereas float arithmetic is inherently imprecise, rounds on the the last bit and that such rounding errors accumulate.

===== Integer =====

This represents arbitrary precision integral numbers. Conversion and memory allocation is completely automatic.
 Thus, without danger of overflow, you can write:
x = 1234567890 * 12345678901234567890 / 10
to get:
1524157875171467887501905210

or:
x = 100.factorial();
to get the huge number:
933262154439441526816992388562667004907159682643816214685929638952175999932299156089
41463976156518286253697920827223758251185210916864000000000000000000000000

Small integer values (smaller than 32 or 64bit, depending in the underlying hardware's native word length) are stored more efficiently than large integers - however, the conversion and representation as used by the system is transparent and automatic.
The same is true for mixed mode arithmetic between small and large integers.

Occasionally it is required to perform modulo arithmetic in 32 or 64bit; for example to reproduce or check values as generated by C or Java programs. For this, use methods from the "''special modulo''" category, such as "<code>add_32()</code>", "<code>add_32u()</code>", "<code>mul_32()</code>" etc. Use a [[Tools_ClassBrowser|class browser]] to find those methods.

Integer constants (of arbitrary size) can be given in hexadecimal (Smalltalk: 16rxxx, JavaScript 0xXXXX), octal (Smalltalk: 8rxxx, JavaScript 0XXXX), and binary (Smalltalk: 2rxxx, JavaScript 0bXXXX). In fact, Smalltalk supports any base from 2 to 36 written as rxxx, where is the base. Thus 3r100 is the ternary representation of the integer 9.
For ease of use, Smalltalk also supports 0x, 0o and 0b radix prefixes (hex, octal and binary).

Overview: [http://live.exept.de/doc/online/english/overview/basicClasses/numeric.html#INTEGER More Info]
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,Integer Class Documentation]

===== Float =====

Float represents double precision IEEE floating point numbers (64bit).
Although seldom needed, conversion to single precision (32bit) and high precision (80bit/128bit, depending on the underlying hardware) is possible via the ''asShortFloat()'' and ''asLongFloat()'' conversion functions. Notice that the actual precision of longFloat numbers depends on the CPU: x86 and x86_64 provide 80bits, Sparc and a few other CPUs provide 128 bits.

For more precision, additional classes called "<code>QDouble</code>" and "<code>LargeFloat</code>" are provided: QDouble provides roughly 200 bits (70 digits) of precision, and LargeFloat offers an arbitrary (configurable) precision. Both are described in the [[Numeric Limits/en|Numeric Limits]] and [[Number_API_Functions|Number API Functions]] documents.

 [[Number_API_Functions|Number API Functions]]
 Overview: [http://live.exept.de/doc/online/english/overview/basicClasses/numeric.html#FLOAT More Info] in the Smalltalk/X online documentation
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,Float Class Documentation]
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,ShortFloat ShortFloat],
[http://live.exept.de/ClassDoc/classDocOf:,LongFloat LongFloat],
[http://live.exept.de/ClassDoc/classDocOf:,QDouble QDouble]

Class Documentation
 Details on QDoubles in [https://www.davidhbailey.com/dhbpapers/qd.pdf https:/www.davidhbailey.com/dhbpapers/qd.pdf].

====== Float Rounding Errors ======
Be reminded that floating point arithmetic is inherently inaccurate: there will almost always be rounding errors on the last bit. The reason is inherent in that most rational numbers simply cannot be represented as the sum of powers of two. For example, 0.1 and 0.3 are two of them: no sum of powers of two (1/2, 1/4, 1/8, ...) is able to represent these numbers exactly. Thus, there will definitely be an error in the last bit of the stored float value.

Typically, print functions (which convert floating point values to a string representation) will "cheat" and round on the last bit. However, if you operate with such numbers (i.e. add, multiply, etc.) these rounding errors will accumulate and may finally add up to more than one bit of error. When this happens, the print function will no longer round up, and you will get the typical ".999999" result strings.

As an example, try adding 0.3 a thousand times, as in:

|t|
t := 0.3.
1000 timesRepeat:[t := t + 0.3].
t print
may give "300.300000000006" as a result.

As a consequence, NEVER ever compare floating point values for equality. In the above case, the comparison with "300.3" would return false!

Floating point numbers should always be compared by giving a range (i.e. between x-delta and x+delta) or by giving a number of valid digits or bits, by which to compare.
expecco provides a number of action blocks for this kind of "''almost-equal''" comparisons.

Of course, there are also similar functions in the Float class, in case you need this in elementary Smalltalk or JavaScript code.

And also: NEVER ever compute monetary values using floating point - or your legal advisor will blame you for missing Cents in the invoice. Monetary values should never be processed with floats (expecco provides a ScaledDecimal number type for that, as described below).

Problems with numbers are discussed in detail in "[[Numeric Limits/en|Numeric Limits]]".

===== Fraction =====

Fractions are arbitrary-precision rational numbers. You will get them when dividing two integers and the result is not integral. Fractions represent an exact result, in contrast to floats, which are only approximations.

For example:
1 / 3
returns a fractional result with a numerator of 1 and a denominator of 3 (as opposed to the Smalltalk // operator, which truncates the result of the division to an integer).

Fractions have the advantage of avoiding rounding errors. Thus, when the above fraction is divided by 3, you will get ''(1/9)'', which we can multiply by 9 to get the exact ''1'' (an integer) without any rounding error. Be reminded that this is typically not the case with Float or Double precision numbers. Due to rounding errors on the last bit, you will often get 0.9999999 as a result there (even though printf may "cheat" and round it to "1.0", as long as the error is in the last bit only; however, when doing multiple operations in a row, these errors accumulate into the next bit, and rounding will no longer generate a "nice looking" output).

Fraction results are automatically reduced - therefore, when adding ''(1/3) + (2/6)'', you will get ''(2/3)''.
 And if you add another ''(1/3)'' to it, you will get an exact ''1''.

Be aware that fractional arithmetic is done by software, whereas floating point arithmetic is done by CPU instructions.
Therefore, floating point arithmetic is usually faster.

Overview: [http://live.exept.de/doc/online/english/overview/basicClasses/numeric.html#FRACTION More Info]
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,Fraction Class Documentation]

===== ScaledDecimal =====

ScaledDecimal (also called "''FixedPoint''") numbers are decimals, with a configurable number of post-decimal digits. They are typically used when dealing with money. Like fractions, they avoid rounding errors. When printed, they round in their last digit, however, the exact information is always kept for further processing. ScaledDecimal numbers are perfect to represent money and other fractional data, which must be represented with a fixed number of post-decimal digits. Internally, fixed point numbers are represented as fractions with a power-of-10 denominator.
 
ScaledDecimal numbers are also great to print tabular data; for example: <code>someNumber as ScaledDecimal:3</code> will print the number with and rounded to 3 post-decimal digits.

 Overview: [http://live.exept.de/doc/online/english/overview/basicClasses/numeric.html#FIXEDPOINT More Info]
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,FixedPoint Class Documentation]

===== Complex=====

Complex numbers with real and imaginary part are sometimes used in technical/physical applications.
They can be read as "<code>a * b i</code>", for example: "<code>5 + 3i</code>" represents the complex number with 5 as real and 3 as imaginary part.

Complex numbers can result from math functions such as sqrt and log (by default, these raise an error, which can be ignored for a complex result)

 Reference: [http://live.exept.de/ClassDoc/classDocOf:,Complex Class Documentation]

===== Number =====

The Number type is an abstract union type which includes all of the above types. Thus, a variable or pin declared as being of "<code>Number</code>" type can take any of the above values. Due to the polymorphic implementation of the underlying numeric class library, most operations can be passed any of the above values (even mixing arguments is possible). For example, the "[Add]" elementary block, which is implemented by simply calling the Smalltalk "+" operation, is able to deal with any combination of argument types.
 Overview: [http://live.exept.de/doc/online/english/overview/basicClasses/numeric.html#NUMBER More Info]
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,Number Class Documentation]

==== String Types ====

Strings can come in three flavours (subclasses of CharacterArray), depending on how many bits are required to encode the character's code point. In general, Unicode is used internally as the encoding. However, converters are available to translate into other encodings, such as JIS or ISO 8859-x.

[[Datei:bulb.png|16px]] Notice that ASCII (0..127) and ISO 8859-1 (0..255) are proper subsets of the Unicode set.
Do not confuse Unicode with UTF-8: Unicode is the numeric value associated to a character and used everywhere within expecco.
UTF-8 is an encoding format for data interchange of Unicode characters. UTF-8 is NOT used inside expecco, only for data exchange with the external world (see "[[String_API_Functions#Encoding_.2F_Decoding|Encoding and Decoding]]" in the String API doc).

In most situations, you do not need to care for the actual number of bits required to store the characters, and expecco/Smalltalk takes care of the actual representation in memory. However, when dealing with the external world (files, sockets, devices), it may be required to perform explicit conversions to/from wider formats or different encodings (UTF-8, UTF-16, etc.)

===== String=====

This is used to represent character strings, where each individual character has a one-byte encoding. I.e. the values are 0..255.
Individual characters of a string can be accessed by an integral index starting with 1 in both Smalltalk and JavaScript. The String class provides many useful functions for substring searching, matching, concatenation/replacing etc.
Also, because String inherits all functions from the Collection superclass hierarchy, all enumeration, mapping, filtering functions are also applicable to strings.
 See also: [[String API Functions | ''Most Useful String Functions'']] and [[Collection API Functions | ''Most Useful Collection Functions'']]
 Overview: [http://live.exept.de/doc/online/english/overview/basicClasses/collections.html#STRING More Info]
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,String Class Documentation]

===== Unicode16String =====

This is used to represent character strings, where at least one character needs a two-byte encoding. I.e. any character's code point is in the range 0x0100 .. 0xFFFF. In fact, there is even a Unicode32String class (see below), which supports the full four-byte Unicode character set. But in practice, such strings are very rarely ever encountered or needed.

===== Unicode32String =====

This is used to represent character strings, where at least one character needs more than a two-byte encoding. I.e. any character's code point is above 0xFFFF. Such strings are very rarely ever encountered or needed.

===== Character =====
Individual characters (as extracted from a string or possibly read from a file) are represented as instances of the Character class. Queries are available to ask the character for its type (isLetter, isDigit etc.) or its Unicode encoding (codePoint). There is virtually no limit and every character from the full Unicode set (e.g. even above 0xFFFF) can be represented by instances of the Character class.
 Overview: [http://live.exept.de/doc/online/english/overview/basicClasses/misc.html#CHARACTER More Info]
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,Character Class Documentation]

==== Collection Types ====

Smalltalk and therefore also expecco provides a very complete set of collection types which are tuned for different access patterns or memory consumption.
An introductory overview on the collection classes is found in the
 Most Useful API: [[Collection API Functions | Most Useful Collection Functions]]
 Overview: [http://live.exept.de/doc/online/english/overview/basicClasses/collections.html Collections Overview] of the [http://live.exept.de/doc/online/english/TOP.html Smalltalk/X online documentation].
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,Collection Class Documentation]

The following paragraphs list the most used collection classes.
Notice, that Smalltalk provides many more container classes, so please take a look at the online documentation or take a life tour with the browser.

===== Array =====

Ordered, fixed size, indexed by an integral index starting with 1 in both Smalltalk and JavaScript.
Can store any type of object, and storage requirements are 1 machine word per element (i.e. arrays store pointers to the elements). As the size is fixed (when created), adding and removing of
elements is not possible. Use one of the other collections (OrderedCollection, Set or Dictionary) if the number
of elements needs to change later or is not known in advance.
 When accessing elements by index, access time complexity is constant O(1). A search for an element in an Array (using <code>includes:</code>, <code>indexOf:</code>, <code>findFirst:</code> or similar methods) has O(N) time complexity (because the search is linear through all elements of the array).
 Overview: [http://live.exept.de/doc/online/english/overview/basicClasses/collections.html#ARRAY More Info]
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,Array Class Documentation]

===== ByteArray =====
Ordered, fixed size, indexed by an integral index starting with 1.
 ByteArrays can only store very small byte-valued unsigned integers (0..255), and allocate 1 byte per element. Access time and complexity are like with ordinary arrays, but the required memory is much less. ByteArrays are used to represent the contents of binary data, binary files, bitmap images, protocol elements (data packets) or low level memory dumps.
 UInt8Array is an alias for ByteArray.
 Overview: [http://live.exept.de/doc/online/english/overview/basicClasses/collections.html#BYTEARRAY More Info]
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,ByteArray Class Documentation]

===== SignedByteArray =====
Ordered, fixed size, indexed by an integral index starting with 1.
 These store very small 8bit signed integer values (-128..127), requiring 1 byte of storage per element.
 Int8Array is an alias for SignedByteArray.
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,SignedByteArray Class Documentation]

===== BitArray =====
Ordered, fixed size, indexed by an integral index starting with 1.
 BitArrays can only store tiny bit-valued unsigned integers (0..1), but only need one byte of storage for every 8 elements.
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,BitArray Class Documentation]

===== BooleanArray =====
Ordered, fixed size, indexed by an integral index starting with 1.
 BooleanArrays can only store booleans (false..true), but only need 1 byte for every 8 stored boolean elements.
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,BooleanArray Class Documentation]

===== FloatArray =====
Ordered, fixed size, indexed by an integral index starting with 1.
 FloatArrays store short IEEE floats (32bit) and allocate 4 bytes per element.
Access times and complexity are like those of regular arrays, but they require much less memory. FloatArrays are often used for data interchange with C language functions or in data acquisition scenarios (series of measurement values).
 Float32Array is an alias for FloatArray, and preferable, as it makes the precision explicit, und thus the code more readable.
 Overview: [http://live.exept.de/doc/online/english/overview/basicClasses/collections.html#FLOATARRAY More Info]
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,FloatArray Class Documentation]

===== DoubleArray =====
Ordered, fixed size, indexed by an integral index starting with 1.
 DoubleArrays store IEEE doubles (64bit) and allocate 8 bytes per element.
These are used in similar situations as FloatArrays.
 Float64Array is an alias for DoubleArray, and preferable, as it makes the precision explicit, und thus the code more readable.
 Overview: [http://live.exept.de/doc/online/english/overview/basicClasses/collections.html#FLOATARRAY More Info]
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,DoubleArray Class Documentation]

===== HalfFloatArray =====
Ordered, fixed size, indexed by an integral index starting with 1.
 HalfFloatArray can only store IEEE half floats (16bit) and allocate 2 bytes per element.
: [[Datei:bulb.png|16px]] Notice that half floats have a very low precision and are seldom used.
: Exceptions are game programs and 3D graphics accelerators which preserve memory by using this very compact format for depth information, texture attributes and some audio formats. They are also used with AI programs in neural networks.
 Float16Array is an alias for HalfFloatArray , and preferable, as it makes the precision explicit, und thus the code more readable.

===== IntegerArray =====
Ordered, fixed size, indexed by an integral index starting with 1.
 These store small 32bit unsigned integer values (0..0xFFFFFFFF) and require 4 bytes of storage per element.
 UInt32Array is an alias for IntegerArray, and preferable, as it makes the precision explicit, und thus the code more readable.
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,IntegerArray Class Documentation]

===== SignedIntegerArray =====
Ordered, fixed size, indexed by an integral index starting with 1.
 They store small 32bit signed integer values (-0x800000000..0x7FFFFFFF), requiring 4 bytes of storage per element.
 Int32Array is an alias for SignedIntegerArray, and preferable, as it makes the precision explicit, und thus the code more readable.
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,SignedIntegerArray Class Documentation]

===== WordArray =====
Ordered, fixed size, indexed by an integral index starting with 1.
 They store small 16bit unsigned integer values (0..0xFFFF), allocating 2 bytes per element.
 UInt16Array is an alias for WordArray, and preferable, as it makes the precision explicit, und thus the code more readable.
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,WordArray Class Documentation]

===== SignedWordArray =====
Ordered, fixed size, indexed by an integral index starting with 1.
 They store small 16bit signed integer values (-0x8000..0x7FFF), allocating 2 bytes per element.
 Int16Array is an alias for SignedWordArray, and preferable, as it makes the precision explicit, und thus the code more readable.
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,SignedWordArray Class Documentation]

===== LongIntegerArray =====
Ordered, fixed size, indexed by an integral index starting with 1.
 They store small 64bit unsigned integer values (0..0xFFFFFFFFFFFFFF), allocating 8 bytes per element.
 UInt64Array is an alias.
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,LongIntegerArray Class Documentation]

===== SignedLongIntegerArray =====
Ordered, fixed size, indexed by an integral index starting with 1.
 These store small 64bit signed integer values (-0x80000000000000000..0x7FFFFFFFFFFFFFFF), allocating 8 bytes per element.
 Int64Array is an alias.
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,SignedLongIntegerArray Class Documentation]

===== ComplexFloatArray and ComplexDoubleArray =====
Ordered, fixed size, indexed by an integral index starting with 1.
 These store complex numbers as pairs of IEEE floats (32bit) or doubles (64bit) and allocate 8/16 bytes per element.
These are used in similar situations as FloatArrays and DoubleArrays.
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,ComplexFloatArray] [http://live.exept.de/ClassDoc/classDocOf:,ComplexDoubleArray]

===== OrderedCollection =====
Ordered, variable size, indexed by an integral index starting with 1.
 OrderedCollections can store any type of object and are specifically tuned for adding/removing elements at either end.
 Access time to elements by index has a time complexity of O(1).
 Insertion and remove at either end approach O(1), but is O(n) for inner elements, because the elements are moved inside a linear container.
When searching for an element in an OrderedCollection (using <code>includes:</code>, <code>indexOf:</code> or similar methods), time complexity is O(n) (because a linear search is done).

Java users will recognize the similarity to "''ArrayLists''".

Note: For very big or lightly sparse collections, you can use a [http://live.exept.de/ClassDoc/classDocOf:,SegmentedOrderedCollection SegmentedOrderedCollection]. This uses a hierarchy of buckets and does not need storage for big unused regions inside the collection. However, due to the additional computations, the breakeven in performance compared to regular OrderedCollections is usually at around 100K to 1M elements.

Note: For very very big collections (millions of elements) which are very lightly filled, use a [http://live.exept.de/ClassDoc/classDocOf:,SparseArray SparseArray]. This only keeps the filled slots, and is great, if you have only a few valid elements inside a virtually huge index space.

Overview: [http://live.exept.de/doc/online/english/overview/basicClasses/collections.html#ORDCOLL More Info]
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,OrderedCollection Class Documentation]

===== SortedCollection =====
Sorts itself, variable size, indexed by an integral index starting with 1.
 SortedCollections can store any type of object for which a order relationship is either implicit (i.e. the elements responds to the "<code><</code>" (less) message) or for which an explicit comparison block can is given (i.e. you provide a sort-block, which takes two elements and returns a boolean depending on the ordering).

By default, sorting is by ascending order based on the "<code><</code>"-message. However, the sort order can be arbitrarily changed by setting the sortBlock, a two-argument JS-function or a two-argument Smalltalk block which should return true, if its first argument is to be "''considered''" smaller than the order (i.e. the default sort block is "<code>[:a :b | a < b]</code>" or in Javascript: "<code>(a,b) => a < b</code>).

Access time complexity by numeric index is O(1). When searching for an element in a SortedCollection (using <code>includes:</code>, <code>indexOf:</code> or similar methods); time complexity is O(log n), because a binary search can be done. Insertion and remove is O(1) for the first and last element, O(log n + n) for inner elements, because the insert index is first searched, then elements are moved inside a linear container.

When a big sorted collection is created, it is faster to first create it as a non-sorted collection (OrderedCollection) and then converting the whole collection via <code>asSortedCollection</code>, instead of adding individual elements one-by-one.
 Overview: [http://live.exept.de/doc/online/english/overview/basicClasses/collections.html#SORTCOLL More Info]
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,SortedCollection Class Documentation]

===== Set =====
Unordered, variable size, keeps a single reference only, per equal element.
 Sets can store any type of object.
When searching a Set for an element (eg. using the <code>includes:</code> method), time complexity approaches O(1), because the search can be done based on a hashing algorithm in asymptotic constant time (however, the time to compute the hash of an element may affect the effective execution time; it should not be too slow). For very small sets, the hash-computation time might be long compared to the time it takes to compare elements. It may then be faster to simply use an Array or OrderedCollection and do a sequential search (use eg. "includes:", "indexOf:" or "anySatisfy:").

 Overview: [http://live.exept.de/doc/online/english/overview/basicClasses/collections.html#SET More Info]
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,Set Class Documentation]
 In addition to the unordered Set, useful classes are also <code>[http://live.exept.de/ClassDoc/classDocOf:,OrderedSet OrderedSet]</code> and <code>[http://live.exept.de/ClassDoc/classDocOf:,SortedSet SortedSet]</code>.

===== Bag =====
Unordered, variable size, keeps a count, per equal element. Adding, removing and insertion check all run in O(1).
Can store any type of object.
 Bags are similar to Sets, but keep the number of occurrences of each element. Thus, bags are perfect to count the number of elements in a collection, for example words and word counts in a document.
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,Bag Class Documentation]

===== Dictionary =====
Unordered, variable size, implements arbitrary key-value mappings.
 Dictionaries can store any type of object and use any kind of object as key.
When accessing or searching an element in a Dictionary (using <code>at:</code>, <code>includesKey:</code> and similar methods), the time complexity asymptotically approaches O(1), because the key search is based on a hashing algorithm. Notice, that the same value may be stored multiple times in a dictionary (i.e. stored under multiple keys).
Asking for the presence of a particular '''value''' in the dictionary (i.e. the reverse query without key) still has O(N) time complexity.

If you need fast access both via the key and the value, either use an additional reverse mapping dictionary, or store
an additional ''value''->''key'' mapping in the same dictionary (if the key and value spaces are disjoint).

Java users will know a subset of the dictionary functionality as "''Hashtable''".

Overview: [http://live.exept.de/doc/online/english/overview/basicClasses/collections.html#DICTIONARY More Info]
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,Dictionary Class Documentation]

===== OrderedDictionary =====
Ordered, variable size, implements arbitrary key-value mappings.
Can store any type of object and use any kind of object as key.
Being similar to dictionaries, these remember the order by which elements were added. It provides both access by hash-key and access by index (which is the order in which elements have been added). When enumerated, elements are processed in that order. Creation of an OrderedDictionary is somewhat slower than for Dictionary or OrderedCollection, but access by either numeric or hashkey is fast with O(1) time complexity.
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,OrderedDictionary Class Documentation]

===== OrderedSet =====
This is very similar to a Set, but remembers the order in which elements were added, and provides index read access methods. When enumerated, the elements are generated in this order.

===== Queue =====
Ordered, variable size.
Can store any type of object. Queues are especially tuned for adding elements at one end, and removing them at the other. The internal representation uses a buffer in round-robin fashion. Both adding and removal are done on O(1) time.
 Overview: [http://live.exept.de/doc/online/english/overview/basicClasses/collections.html#QUEUE More Info]
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,Queue Class Documentation]

If multiple processes are accessing the same queue concurrently, use a <code>[http://live.exept.de/ClassDoc/classDocOf:,SharedQueue SharedQueue]</code>, which is implicitly synchronized.

===== SharedCollection =====
Any collection can be wrapped into a ''SharedCollection'' to add synchronization locks around its access functions. These should be used if multiple processes (threads) are going to access (i.e: update) the collection simultaneously.
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,SharedCollection Class Documentation]

===== BTree, AATree, BinaryTree =====
Combining the functionality of <code>Dictionary</code> and <code>SortedCollection</code>, these keep their elements in a sorted order, indexed by a key, both of which can be arbitrary objects.
In contrast to dictionaries, which use hashing, these use a tree-like representation and guarantee both asymptotic O(log N) worst case and average runtime. (Dictionaries have a much better typical time complexity of O(C), but also a worst case of O(N), if the hash keys are badly distributed). These trees are self balancing to avoid the linear worst case access time of non balanced trees. [[http://live.exept.de/ClassDoc/classDocOf:,BTree Class Documentation]]

There is also a non-balancing BinaryTree, which is slightly faster (by not balancing), but its worst case access times may degenerate to O(N), if elements are added non-randomly. Reference: [http://live.exept.de/ClassDoc/classDocOf:,BinaryTree Class Documentation]

===== Interval and GeometricSeries =====

This represent ranges of numbers as in "<CODE>(1 to:5)</CODE>" or "<CODE>(1 to:10 by:2)</CODE>" or "<CODE>(7 to:4 by:-1)</CODE>", which represent collections of numbers [1,2,3,4,5], [1,3,5,7,9] and [7,6,5,4] respectively.

GeometricSeries are similar, but have a constant factor between elements, instead of a constant difference. For example, the "<CODE>(GeometricSeries from:1 to:64 byFactor:2)</CODE>" represents the collection of [1,2,4,8,16,32,64]".

Intervals and GeometricSeries can be used wherever a readonly collection can be used.
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,Interval Interval Class Documentation] and [http://live.exept.de/ClassDoc/classDocOf:,GeometricSeries GeometricSeries Class Documentation]

==== Stream Types ====

Streams are accessors for either internal collections or external files, sockets and other character oriented I/O devices.
They are created by either "''opening''" a file or device or by creation "''on''" a numerical indexable collection object (String, Array, OrderedCollection etc.).
Once created, readstreams deliver the next element via a "''next''()" operation, writestreams append elements via the "''nextPut(e)''" operation.
In addition to the above elementary functions, bulk read/write and linewise read/write and various other functionality is provided.

An introductory overview on the stream classes is found in the
[[http://live.exept.de/doc/online/english/overview/basicClasses/streams.html Streams Overview]] of the [[http://live.exept.de/doc/online/english/TOP.html Smalltalk/X online documentation]].

===== ExternalStream =====
A common superclass providing bytewise, blockwise and linewise access to any stream of the underlying operating system. Concrete subclasses are Socket, Filestream, Console Streams, PTYStream etc.
 Overview: [http://live.exept.de/doc/online/english/overview/basicClasses/streams.html#FILESTREAM More Info]
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,ExternalStream Class Documentation]

===== FileStream =====
Provide bytewise, blockwise or linewise access to the underlying file system.
 Overview: [http://live.exept.de/doc/online/english/overview/basicClasses/streams.html#FILESTREAM More Info]
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,FileStream Class Documentation]

===== CharacterWriteStream =====
A special stream usable for mixed single- and multibyte characters (i.e. Unicode). This stream starts to collect into a single byte string buffer, but switches automatically to a multibyte character string as required.
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,CharacterWriteStream Class Documentation]

===== Socket =====
Provides low level bytewise, blockwise or linewise access to a communication socket. Typically, but not limited to TCP/IP connections.
 Overview: [http://live.exept.de/doc/online/english/overview/basicClasses/streams.html#FILESTREAM More Info]

Reference: [http://live.exept.de/ClassDoc/classDocOf:,Socket Class Documentation]

There are a number of useful companion classes which deal with host addresses:
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,SocketAddress SocketAddress],
[http://live.exept.de/ClassDoc/classDocOf:,SocketAddress IPSocketAddress] and
[http://live.exept.de/ClassDoc/classDocOf:,SocketAddress IPv6SocketAddress].

===== PipeStream =====
These are used to read/write from/to another program's standard input or standard output. For details, consult a Unix programmer's manual.
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,PipeStream Class Documentation]

===== Filename =====
Represents names of files in the filesystem. Provides many useful query functions for file size, access- and modification time, parent directory, children, path queries etc.
 Most Useful API: [[Filename API Functions]]
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,Filename Class Documentation]

==== Encoders / Decoders ====

The
[http://live.exept.de/ClassDoc/classDocOf:,CharacterEncoder CharacterEncoder] class provides a number of functions to encode/decode strings into various other encodings;
for example, to read an ISO 8859-7 encoded string,
use:
decodedString :=
(CharacterEncoder encoderFor:#'ISO8859-7')
decodeFrom:encodedString.
and vice versa:
encodedString :=
(CharacterEncoder encoderFor:#'ISO8859-7')
encodeFrom:originalString.

By the time of writing, the following encodings are supported (many are aliases of others):

adobe-fontspecific ansi_x3.4-1968 arabic ascii ascii7 asmo-708
big5
cns11643 cp-037 cp-37 cp-437 cp10000 cp1250 cp1251 cp1252 cp1253 cp1254 cp1255 cp1256 cp1257 cp367 cp437 cp878 cyrillic
ebcdic ebcdic-037 ecma-114 ecma-118
gb2312 gb2312.1980 gb2312.1980-0 greek
hangul hebrew
ibm-367 ibm-437 ibm-819 ibm-cp367 ibm-cp437 ibm-cp819 iso-10646-1 iso-8859-1 iso-8859-10 iso-8859-11 iso-8859-13 iso-8859-14 iso-8859-15 iso-8859-16 iso-8859-2 iso-8859-3 iso-8859-4 iso-8859-5 iso-8859-6 iso-8859-7 iso-8859-8 iso-8859-9 iso-ir-100 iso-ir-101 iso-ir-109 iso-ir-110 iso-ir-126 iso-ir-127 iso-ir-138 iso-ir-144 iso-ir-148 iso-ir-157 iso-ir-203 iso-ir-6 iso10646-1 iso10646_1 iso646-us iso8859 iso8859-1 iso8859-10 iso8859-11 iso8859-13 iso8859-14 iso8859-15 iso8859-16 iso8859-2 iso8859-3 iso8859-4 iso8859-5 iso8859-6 iso8859-7 iso8859-8 iso8859-9 iso8859_1 iso8859_10 iso8859_11 iso8859_13 iso8859_14 iso8859_15 iso8859_16 iso8859_2 iso8859_3 iso8859_4 iso8859_5 iso8859_6 iso8859_7 iso8859_8 iso8859_9
java javaText jis0201 jis0208 jis0212 jisx0201.1976-0 jisx0208 jisx0208.1983-0 jisx0208.1990-0 johab
koi7 koi8-r koi8-u ksc5601
latin-1 latin-10 latin-2 latin-3 latin-4 latin-5 latin-6 latin-7 latin-8 latin-9 latin-celtic latin1 latin10 latin2 latin3 latin4 latin5 latin6 latin7 latin8 latin9
mac-arabic mac-centraleurope mac-centraleuropean mac-croatian mac-cyrillic mac-dingbats mac-farsi mac-greek mac-hebrew mac-iceland mac-japanese mac-korean mac-roman mac-romanian mac-symbol mac-thai mac-turkish macarabic maccentraleurope maccentraleuropean maccroatian maccyrillic macdingbat macdingbats macfarsi macgreek machebrew maciceland macintosh macjapanese mackorean macroman macromanian macsymbol macthai macturkish microsoft-ansi microsoft-arabic microsoft-baltic microsoft-cp1250 microsoft-cp1251 microsoft-cp1252 microsoft-cp1253 microsoft-cp1254 microsoft-cp1255 microsoft-cp1256 microsoft-cp1257 microsoft-cp437 microsoft-cyrillic microsoft-easteuropean microsoft-greek microsoft-hebrew microsoft-turkish ms-ansi ms-arabic ms-baltic ms-cp1250 ms-cp1251 ms-cp1252 ms-cp1253 ms-cp1254 ms-cp1255 ms-cp1256 ms-cp1257 ms-cp367 ms-cp437 ms-cp819 ms-cyrillic ms-default ms-easteuropean ms-ee ms-greek ms-hebrew ms-oem ms-turkish next
nextstep
sgml
thai
us-ascii utf-16b utf-16be utf-16e utf-16le utf-8 utf-8-mac utf16b utf16be utf16l utf16le utf8 utf8-XML utf8-mac
windows-1250 windows-1251 windows-1252 windows-1253 windows-1254 windows-1255 windows-1256 windows-1257 windows-latin1

For base64 encoding, refer to the
[http://live.exept.de/ClassDoc/classDocOf:,Base64Coder Base64Coder]
class, or use the string messages: <code>base64Encoded</code> and <code>base64Decoded</code>.

For utf8 encoding/decoding, use the string messages: <code>utf8Encoded</code> and <code>utf8Decoded</code>.

==== Other useful Types ====

===== Date =====
Represents a calendar date. Instances can be created with eg. "<code>Date today</code>", by giving day/month/year or a calendar day. Instances offer a large number of queries, such as weekday, dayInWeek, leapYear etc.
 Overview: [http://live.exept.de/doc/online/english/overview/basicClasses/misc.html#DATE More Info]
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,Date Class Documentation]

===== Time =====
Represents a time-of-day in second resolution. Instances are created with "<code>Time now</CODE>" or by giving hour/minute/seconds.
 Overview: [http://live.exept.de/doc/online/english/overview/basicClasses/misc.html#TIME More Info]
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,Time Class Documentation]

===== Timestamp (Date and Time) =====
Represents a timestamp. With the 18.1 release, the resolution has been improved to sub-nanosecond resolution, although internal timestamps as generated by the operating system will usually not generate such fine grained values (some systems will only generate, 1 millisecond resolution stamps).

Update: now the resolution supported by Timestamps is 1 picosecond, and microsecond times are also supported on Windows systems.

For backward compatibility, the default resolution is 1 millisecond for internally generated stamps, and whatever resolution is provided when stamps are read from an external source. When printed, the default print format includes 3 millisecond digits, but a separate print generator can produce higher resolution strings (in 18.1).

The Timestamp class has been enhanced to support dates before 1.1.1970 and after 2036, which are typical restrictions of systems which represent times as "''seconds since the epoch''" in a 32bit integer. Expecco timestamps handle values before and after those dates, although no calendar adjustments are done for timestamps before the julian/gregorian switch (i.e. this affects weekdays, leap years, etc. before 1582, which are very unlikely to be encountered in technical environments ;-) ).
 Overview: [http://live.exept.de/doc/online/english/overview/basicClasses/misc.html#TIMESTAMP More Info]
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,Timestamp Class Documentation]

===== TimeDuration =====
Represents an amount of time, to represent time intervals in picosecond resolution.

When reading from a string or stream, a unit-specifier character is allowed to specify milliseconds (ms), seconds (s), minutes (m), hours (h) or days (d). For example, "<code>1h 20s</code>" specifies 1 hour and 20 seconds.

As a programmer, you can write (in Smalltalk): "<code>1 hours + 20 seconds</code>"

Creation:
* TimeDuration fromString: '''aString'''
* TimeDuration fromSeconds: '''aNumber'''
* TimeDuration fromMinutes: '''aNumber'''
* TimeDuration fromHours: '''aNumber'''
* TimeDuration fromMilliseconds: '''aNumber'''
* TimeDuration fromMicroseconds: '''aNumber'''
* TimeDuration fromNanoseconds: '''aNumber'''
* TimeDuration fromPicoseconds: '''aNumber'''
* TimeDuration days: '''dayNumber''' hours: '''hourNumber''' minutes: '''minuteNumber''' seconds: '''secondsNumber'''

Overview: [http://live.exept.de/doc/online/english/overview/basicClasses/misc.html#TIMEDURATION More Info]
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,TimeDuration Class Documentation]

===== Delay =====
Delay is a utility providing timed delay functions. Most useful are (written in Smalltalk):
Delay waitForSeconds: n. (arg is a number)
and:
Delay waitFor: n seconds. (arg is a time duration)
and:
Delay waitUntil: timestamp. (arg is a timestamp)

or (written in JavaScript):
"<code>Delay.waitForSeconds(n)</code>";
"<code>Delay.waitFor(n.seconds())</code>";
and
"<code>Delay.waitUntil(timestamp)</code>";

Reference: [http://live.exept.de/ClassDoc/classDocOf:,Delay Class Documentation]

==== CTypes ====

These types describe C-data structures. They are needed when data is exchanged with DLL functions or is to be read/written in binary from/to a file or a communication channel.

CTypes are usually parsed from a string using the C Parser, which is invoked by expecco when a type definition starts with a comment like "/* C: */".
But of course, the C-Parser can also be invoked explicitly in a workspace or programmatically via an elementary block.
The following example would create a C-type from a structure definition string (in JavaScript code):
t = CParser.parseDeclaration("
struct s {
unsigned long DPR_Address;
unsigned long DPR_Length;
unsigned long PortAddress;
struct p {
unsigned char ProtocolID;
union u {
uint16 dpInOutAreaSize;
uint16 dpInAreaSize;
} Parameter;
} Protocol[4];
};
");
the type in variable "<code>t</code>" can then be instantiated by sending it a "<code>new</code>" message:
cDatum = t.new();
or with:
cDatum = t.malloc();
The difference is that "<code>new</code>" allocates the bytes in the regular garbage collected expecco memory (which may move objects),
whereas "<code>malloc</code>" allocates in pinned (not moving) memory on the C heap. Thus references to such malloc'd memory can be passed to DLL code which wants to keep a reference to it, whereas C-data allocated with <code>new</code> can only be used temporarily by C code and will vanish sooner or later after the call returns.

You can inspect the created instance via the inspector (evaluate: "<code>cDatum.inspect()</code>").

Individual fields of the c-datum are accessed via the following functions:
* <code>cDatum.memberAt(fieldName)</code> retrieves a field. If the field is a composite datum (array or structure), a new datum is extracted (i.e. a structure copy is made).

* <code>cDatum.at(index0Based)</code> retrieves an indexed array element as a copy.

* <code>cDatum.memberAtPut(fieldName, value)</code> stores a field. If the field is a composite datum (array or structure), the whole value is copied.

* <code>cDatum.atPut(index0Based)</code> stores an indexed array element.

* <code>CDatum.refMemberAt(fieldName)</code> creates a pointer to a field. This allows for subfields to be modified.

* <code>cDatum.refAt(index0Based)</code> creates a pointer to an array element.

notice that in JavaScript, indexed access can be written more convenient as "<code>cDatum[index0Based]</code>" and that member field access can be written as "<code>cDatum.fieldName</code>".

For the full protocol of CDatum, please refer to the class code in the
[http://live.exept.de/ClassDoc/classDocOf:,Ctype Class Documentation].
 Additional information is also found in the [[Datatype Element/en#CTypes]] documentation.

=== Additional Standard Objects for JavaScript ===

In order for a "''well known''" environment to be provided to those who know JavaScript, but do not know Smalltalk, mimicri classes (Math) and mimicri protocol has been added to the underlying Smalltalk system. These functions simply call corresponding Smalltalk functions and only exist to provide a JavaScript compatible API which is described below.

Notice that this represents only a small fraction (less than 1/100th) of the real functionality of the base system. In order to find out more about all existing classes, you should open a class browser and navigate through the system yourself (eg. Number and subclasses). There is also a more detailed introduction to the basic classes found in the
[http://live.exept.de/doc/online/english/overview/basicClasses/TOP.html Smalltalk/X Base Classes Documentation].

==== Math ====

===== Constants =====

*'''E''' Euler's constant, the base of the natural logarithm (approximately 2.718 as double precision IEEE number). Same as "<code>Float e</code>" in Smalltalk (or "<code>Math E</code>").

*'''LN10''' Natural logarithm of 10 (approximately 2.302 as double). In Smalltalk, you can use "<code>Float ln10</code>" (or "<code>Math LN10</code>").

*'''LN2''' Natural logarithm of 2 (approximately 0.693 as double). Same as "<code>Float ln2</code>" in Smalltalk.

*'''LOG10E''' Base 10 logarithm of E (approximately 0.434 as double)

*'''LOG2E''' Base 2 logarithm of E (approximately 1.442 as double)

*'''PI''' Pi (approximately 3.14159 as double). Same as "<code>Float pi</code>" in Smalltalk.

*'''SQRT1_2''' Square root of 1/2 (approximately 0.707 as double)

*'''SQRT2''' Square root of 2 (approximately 1.414 as double). Same as "<code>Float sqrt2</code>" in Smalltalk.

===== Min & Max =====

*'''max''' (''number1 , number2,...'') Returns the largest of up to 6 arguments

*'''min''' (''number1, number2,...'') Returns the smallest of up to 6 arguments

===== Miscellaneous =====

*'''abs''' (''aNumber'') Returns the absolute value of aNumber

*'''binco''' (''n, k'') Returns the binomial coefficient C(n,k) (aka. "n over k" or "choose k from n")

*'''cbrt''' (''aNumber'') Returns the cubic root of aNumber

*'''ceil''' (''aNumber'') Returns the smallest integer greater than or equal to aNumber

*'''exp''' (''aNumber'') Returns eaNumber, where aNumber is the argument, and e is Euler's constant, the base of the natural logarithm

*'''fac''' (''aNumber'') Returns the factorial of aNumber

*'''floor''' (''aNumber'') Returns the greatest integer less than or equal to aNumber

*'''gcd''' (''a, b'') Returns the greatest common divisor of a and b

*'''log10''' (''aNumber'') Returns the log base 10 of aNumber

*'''log''' (''aNumber'') Returns the log base E of aNumber


*'''pow''' (''base, exp'') Returns base to the exponent power, that is, baseexp

*'''random''' Returns a pseudo random number between 0 and 1

*'''round''' (''aNumber'') Returns the value of aNumber rounded to the nearest integer

*'''sqrt''' (''aNumber'') Returns the square root of aNumber

*'''trunc''' (''aNumber'') Returns the value of aNumber truncated towards zero (that is: the smallest integer greater or equal if aNumber is negative, or the largest integer less or equal if positive)

===== Trigonometric =====

*'''sin''' (''aNumber'') Returns the sine of aNumber (given in radians)

*'''cos''' (''aNumber'') Returns the cosine of aNumber (given in radians)

*'''tan''' (''aNumber'') Returns the tangent of aNumber (given in radians)

*'''cot''' (''aNumber'') Returns the cotangent of aNumber (given in radians)

*'''csc''' (''aNumber'') Returns the cosecant of aNumber (given in radians)

*'''sec''' (''aNumber'') Returns the secant of aNumber (given in radians)

*'''arcSin''' (''aNumber'') Returns the arcsine (in radians) of aNumber

*'''arcCos''' (''aNumber'') Returns the arccosine (in radians) of aNumber

*'''arcTan''' (''aNumber'') Returns the arctangent (in radians) of aNumber

*'''arcTan2''' (''x, y'') Returns the arctangent of the quotient of its arguments (in radians)

*'''sinh''' / '''cosh''' / '''tanh''' / '''arSinh''' / '''arCosh''' etc. Hyperbolic versions of above

*'''degreesToRadians'''(''d'') / '''radiansToDegrees'''(''r'') Conversions

==== Number ====
===== Properties =====

*'''MAX_VALUE''' The largest representable number. The returned number is 0x7FFFFFFFFFFFFFFF, to mimicri a 64 bit limit on numbers for JS programs ported from other systems. In fact, expecco does not impose any such limit in integer values.

*'''MIN_VALUE''' The smallest representable number. The returned number is -0x8000000000000000, to mimicri a 64 bit limit on numbers for JS programs ported from other systems. In fact, expecco does not impose any such limit in integer values.

*'''NEGATIVE_INFINITY''' Returns the special 'negative infinity' value

*'''NaN''' Returns the special 'not a number' value

*'''POSITIVE_INFINITY''' Returns the special 'positive infinity' value

===== Methods =====

*''aNumber''.'''asFloat''' () Returns a floating-point version of the receiver object. For example: "<code>1.asFloat()</code>" yields the (double precision) floating point number: "1.0". You can also use one of "asFloat32", "asFloat64", "asFloat80", "asFloat128" or "asLargeFloat".

*''aNumber''.'''asInteger''' () Returns an integer version of the receiver object (truncating). For example: "<code>1.0.asInteger()</code>" yields the integer number: "1". Alternatives are ceiling(), floor() and rounded().

*''aNumber''.'''ceiling''' () For non-integral values, ceiling returns the smallest integer which is larger than the receiver. For integers, the original value is returned. For example: "<code>1.4.ceiling()</code>" yields the integer number: "2", whereas "<code>1.ceiling()</code>" returns "1". See also: floor() and rounded().

*''aNumber''.'''floor''' () For non-integral values, floor returns the largest integer which is smaller than the receiver. For integers, the original value is returned. For example: "<code>1.4.floor()</code>" yields the integer number: "1", whereas "<code>1.floor()</code>" returns "1". See also: ceiling() and rounded().

*''aNumber''.'''rounded''' () For non-integral values, rounded returns the nearest integer from rounding. For integers, the original value is returned. For example: "<code>1.4.rounded()</code>" yields the integer number: "1", "<code>1.6.rounded()</code>" yields the integer number: "2" and whereas "<code>1.rounded()</code>" returns "1". See also: ceiling() and floor().

*''aNumber''.'''roundTo''' (''r'') Rounds towards the nearest multiple of r. For example, "<code>1.543.roundedTo(0.01)</code>" returns "1.54" and "<code>1.567.roundedTo(0.01)</code>" returns "1.57". See also: ceiling(), floor() and rounded().

*''aNumber''.'''toExponential''' (''nDigits'') Returns a string representing the number in exponential notation, where nDigits is the number of digits to appear after the decimal point

*''aNumber''.'''toExponential''' (''nDigits, nDigitsAfter'') Returns a string representing the number in exponential notation

*''aNumber''.'''toFixed''' (''nDigits'') Returns a string representing the number in fixed notation, where nDigits is the number of digits to appear after the decimal point

==== Random ====

A built in random generator, which generates linear congruential pseudo random numbers itself. On Unix/Linux operating systems, an additional class called "RandomGenerator" uses the operating system's random generator (<code>/dev/rand</code>). In addition, alternative generators are available as "<code>RandomParkMiller</code>" and "<code>RandomTT800</code>". For most applications, the default generator named "<code>Random</code>" should provide a reasonable random sequence (this will be the "/dev/rand"-based generator on Unix/Linux, and a Cryptographic Hash-based generator on other systems).

*''Random''.'''next ()''' Returns a random number between 0 and 1 (float)

*''Random''.'''next (''n'')''' Returns n random numbers between 0 and 1 (float) as an array

*''Random''.'''nextBoolean ()''' Randomly returns either true or false

*''Random''.'''nextBetween_and_''' (''min, max'') Returns a random float between min and max

*''Random''.'''nextIntegerBetween_and_''' (''min, max'') Returns a random integer between min and max (use 1 and 6, to simulate a dice)

==== Time / Date ====

Time and Date instances provide a rich protocol for all kinds of queries. The list below is only a short extract of the most used methods:

*'''Time now''' Returns the current time

*'''Date today''' Returns the current date

*''aDate''.'''getDate'''() Returns the day of the month (1..31)

*''aDate''.'''getDay'''() Returns the day of the week (0..6); Sunday is 0

*''aDate''.'''getMonth'''() Returns the day of the month (1..12)

*''aDate''.'''getFullYear'''() Returns the year

*''aTime''.'''getHours'''() Returns the hours (0..24)

*''aTime''.'''getMinutes'''() Returns the minutes (0..60)

==== String ====

Be reminded that the String class inherits from CharacterArray, ByteArray, SequentialCollection, Collection and Object. Thus all of those methods are also available (and useful) with strings. Use the browser or take a look at the online documentation for the full protocol (which is much larger than what is listed below).

*''aString''.'''charAt0''' (''index'') Returns the n'th character as a Character instance object, using a 0-based indexing scheme

*''aString''.'''charAt1''' (''index'') Returns the n'th character as a Character instance object, using a 1-based indexing scheme

*''aString''.'''charCodeAt0''' (''index'') Returns the code of the n'th character, using a 0-based indexing scheme

*''aString''.'''charCodeAt1''' (''index'') Returns the code of the n'th character, using a 1-based indexing scheme

*''aString''.'''indexOf0''' (''aCharacter'') Returns the index of aCharacter, using a 0-based indexing scheme; -1 if not found

*''aString''.'''indexOf1''' (''aCharacter'') Returns the index of aCharacter, using a 1-based indexing scheme; 0 if not found

*''aString''.'''lastIndexOf0''' (''aCharacter'') Returns the last index of aCharacter, using a 0-based indexing scheme; -1 if not found

*''aString''.'''lastIndexOf1''' (''aCharacter'') Returns the last index of aCharacter, using a 1-based indexing scheme; 0 if not found

*''aString''.'''quote()''' Wraps the receiver into double quotes (")

*''aString''.'''split''' (''separator'') Splits the string into a collection of substrings using the separator. Warning: the JavaScript split(xxx) function and the Smalltalk split: method have different semantics (and argument order)

*''aString''.'''substr0''' (''index, count'') Extracts a substring starting at the index with the given length, using a 0-based indexing scheme

*''aString''.'''substr1''' (''index, count'') Extracts a substring starting at the index with the given length, using a 1-based indexing scheme

*''aString''.'''substring0''' (''index1'') Extracts a substring starting at the index, using a 0-based indexing scheme

*''aString''.'''substring0''' (''index1, index2'') Extracts a substring between the given indices, using a 0-based indexing scheme

*''aString''.'''substring1''' (''index1'') Extracts a substring starting at the index, using a 1-based indexing scheme

*''aString''.'''substring1''' (''index1, index2'') Extracts a substring between the given indices, using a 1-based indexing scheme

*''aString''.'''toLowerCase''' Returns a copy of the receiver with all chars in lower case

*''aString''.'''toUpperCase''' Returns a copy of the receiver with all chars in upper case

*''aString''.'''trim''' Returns a copy of the receiver with all leading and trailing white space removed

*''aString''.'''trimLeft''' Returns a copy of the receiver with all leading white space removed

*''aString''.'''trimRight''' Returns a copy of the receiver with all trailing white space removed
 

==== Collection (Array) ====

Notice that Array, OrderedCollection, ByteArray, String and others are also inheriting the Collection protocol. Thus the below listed messages can also be applied to instances of those.

*''aCollection''.'''concat''' (''aCollection'') Returns a new collection consisting of the concatenation of the receiver and the argument

*''aCollection''.'''every''' (''filterFunction'') Returns true, if "filterFunction" returns true for all elements

*''aCollection''.'''filter''' (''filterFunction'') Selects elements for which "filterFunction" returns true

*''aCollection''.'''forEach''' (''function'') Applies "function" for each element

*''aCollection''.'''join''' (''seperator'') Joins the strings of the receiver into a new single string using the separator

*''aCollection''.'''map''' (''function'') Returns a new collection collecting the results of applying "function" to each element in sequence

*''aCollection''.'''pop''' Removes and returns the last element of the collection. Modifies the receiver collection as a side effect.

*''aCollection''.'''push''' (''value'') Adds an element to the end of the collection. Modifies the receiver collection as a side effect.

*''aCollection''.'''reduce0''' (''filterFunction'') Applies "function" against two values, reducing from left to right. Function must be declared as: f(previousValue, currentValue, index, arr). Pass 0-based indices to the filter.

*''aCollection''.'''reduce0''' (''filterFunction, initialValue'') Applies "function" against two values, reducing from left to right. Function must be declared as: f(previousValue, currentValue, index, arr). Pass 0-based indices to the filter.

*''aCollection''.'''reduce1''' (''filterFunction'') Applies "function" against two values, reducing from left to right. Function must be declared as: f(previousValue, currentValue, index, arr). Pass 1-based indices to the filter.

*''aCollection''.'''reduce1''' (''filterFunction, initialValue'') Applies "function" against two values, reducing from left to right. Function must be declared as: f(previousValue, currentValue, index, arr). Pass 1-based indices to the filter.

*''aCollection''.'''shift''' Removes and returns the first element of the collection. Same as ''removeFirst''. Notice that this modifies the receiver collection as a side effect.

*''aCollection''.'''slice0''' (''index1, index2'') Extracts a subcollection, using a 0-based indexing scheme

*''aCollection''.'''slice1''' (''index1, index2'') Extracts a subcollection, using a 1-based indexing scheme

*''aCollection''.'''some''' (''filterFunction'') Returns true, if "filterFunction" returns true for any element

*''aCollection''.'''unshift''' (''arg'') Adds an element to the beginning of the collection. Same as ''addFirst''. Notice that this modifies the receiver collection as a side effect.
 

==== Transcript ====

The global variable "<code>Transcript</code>" refers to either the Transcript information window (if it is open) or the standard error stream. As such, it implements most of the stream interface functions. Most noteworthy are:

*Transcript.'''cr''' () Adds a linebreak (i.e. followup text will be shown on the next line)

* Transcript.'''show''' (''arg'') Adds a textual representation of the argument, which can be a string, number or any other object.

* Transcript.'''show''' (''fmt'', ''arg'',...) Like show, but "%i" (i=1..8) sequences in the format argument are expanded by corresponding argument strings. Up to 8 arguments are allowed.

* Transcript.'''showCR''' (''arg'') A combination of show(), followed by a linebreak.

* Transcript.'''showCR''' (''fmt'', ''arg'',...) Like showCR, but "%i" (i=1..8) sequences in the format argument are expanded by corresponding argument strings. Up to 8 arguments are allowed.

and from the inherited write stream interface:

* Transcript.'''nextPut''' (''aChar'') Sends a single character

* Transcript.'''nextPutAll''' (''aString'') Sends a string

* Transcript.'''nextPutLine''' (''aString'') Sends a string followed by a linebreak

Notice that if a prefix string is defined in a variable named "__Transcript_Prefix__", that string is prepended to the output.

 

==== Logger ====

The global variable "<code>Logger</code>" refers to an object which will handle system log messages. This is the underlying Smalltalk framework's logging mechanism, not to be confused with expecco's ''ActivityLog''.

The Logger will filter messages according to their ''severity'', which is one of {<code>debug, info, warn, error, fatal</code>}. Severities are ordered as <code>debug < info < warn < error < fatal</code>.
For filtering, a severityThreshold can be set, and only messages with a higher severity will be reported.

By default, the Logger sends its output to the ''stderr'' stream, which is usually redirected into a (log-)file when expecco runs unattended as a service or controlled by command line arguments.
This behavior can be changed by assigning a different logger to the global "Logger".
Under Unix systems (OSX and Linux), the defaul logger can also be replaced by one which writes to the syslog facility.
 The Logger supports the following protocol:

*Logger.'''debug''' (''message'') logs a debug message

*Logger.'''info''' (''message'') logs an info message

*Logger.'''warn''' (''message'') logs an warning message

*Logger.'''error''' (''message'') logs an error message

*Logger.'''fatal''' (''message'') logs a fatal message
 

=== Expecco Objects ===
Many objects internal to expecco's execution machinery are reachable via elementary code (i.e. from within an elementary-coded action's code).
A lot of useful and required information can be acquired by consulting these objects.
The anchor to all those objects is the "''current activity''" object.

==== Current Activity ====
Within elementary code the activity instance which is executing this piece of code can be accessed via the variable "<code>this</code>" (in Smalltalk: "<code>self</code>"). For every executed action, a new activity object is created. It is usually alive during the execution only (i.e. it is destroyed and its memory reused automatically, after the block's action has finished).

The current activity object supports the following functions:

===== Reporting =====

*'''error''' () Report a defect (in the test). Stops execution.

*'''error''' (''infoString'') Report a defect (in the test) with infoString to be shown in the activity log. Stops execution.

*'''fail''' ( [''infoString''] ) Report a failure (in the SUT) with optional infoString to be shown in the activity log. Stops execution.

*'''inconclusive''' ( [''infoString''] ) Report an inconclusive test. Stops execution.

*'''success''' ( [''infoString''] ) OBSOLETE - see activitySuccess below Finishes the current activity with success.

*'''activitySuccess''' ( [''infoString''] ) Finishes the current activity with success. Actually not needed, because simply returning from an action's execute method is semantically equivalent (however, this allows for early successful finish). Due to the more descriptive name, use this function instead of "<code>success()</code>".

*'''testPass''' ( [''infoString''] ) Finishes the current test case with success. Notice: this aborts the current activity and all of the callers up to the test case level. This behavior is different from activitySuccess's behavior.

*'''pass''' ( [''infoString''] ) Same as testPass (backward compatibility).
 

===== Logging =====

*'''logData''' (''data'') Adds data to the activity log.

*'''logDataFile''' (''fileName'') Adds a file attachment to the activity log.

*'''logError''' (''messageString'') Adds a error message to the activity log.

*'''logError''' (''messageString'', ''detail'') Adds a error message to the activity log.

*'''logWarning''' (''messageString'') Adds a warning to the activity log.

*'''logWarning''' (''messageString'', ''detail'') Adds a warning to the activity log.

*'''logInfo''' (''messageString'') Adds an info message to the activity log.

*'''logInfo''' (''messageString'', detail) Adds an info message to the activity log.

*'''logImageInfo''' (''messageString'', image) Adds an info message with an image (screendump) to the activity log. There is an option in the report generator to include those in the generated pdf-report.

*'''alert''' (''messageString'') Adds a warning message to the activity log, and also shows a DialogBox, which has to be confirmed by the operator. The dialog box and confirmation can be disabled by a settings flag in the "[[Settings_LoggingSettings/en|Execution-Log-Settings]]" dialog (by default, it is disabled).

*'''warn''' (''messageString'') Same as ''alert()'' (for Smalltalk protocol compatibility).

Notice the similarity and difference between "error()" and "logError()": both actually create a log-data entry, but "error()" stops the execution, whereas "logError()" proceeds (maybe, the naming is a bit confusing here...)

 

===== Execution =====

*'''call''' (''calledActionName'') Calls another action without any input values. The called action is specified by the "''calledActionName''" parameter.
*'''call''' (''calledActionName'', ''arg''...) Calls another action with ''argi'' input value(s). The called action is specified by the "''calledActionName''" parameter. Up to 8 arguments are supported.
*'''call_with''' (''calledActionName'', ''inPinValues'') Calls another action passing input values as a collection of values. The called action is specified by the "''calledActionName''" parameter.
*'''call_into''' (''calledActionName'', ''funcReceivingValues'') Not passing any input values (similar to call), for actions with multiple output values or which write multiple values.
*'''call_with_into''' (''calledActionName'', ''inPinValues'', ''funcReceivingValues'') Similar to the above, for actions with multiple output values or which write multiple values.
The called action is specified by the "''calledActionName''" parameter which must be one of:
* a UUID (the called action-block's version- or function-ID),
* a UUID-string (the called action-block's version- or function-ID),
* a name-string (the called action-block's name),
* a direct reference to the action-block object.

Although giving a simple name-string is propably the easiest way to specify the action, it may lead to an error, if multiple actions are found with the same name (which never happens, if a UUID is used). If a UUID is used, this can be either the action's functional- or version-ID. If the version-ID is given, that particular action is called. If a functional-ID is given, the first action which is found to have a matching functional-ID is called. The version-ID is specific, but intolerant to reimports or changes in the called action. Therefore, you should propably use the functional-ID, if you do not want to use the action's name.
 In most "normal" situations, the action's name is unique and good enough.

There is an automatic mechanism, to deal with renaming, in that constant action names are found and replaced.
Also, such action references are found via the "''References''" tree menu item and you'll get a warning if such an action is renamed or removed.

The "''inPinValues''" argument can be either a vector (array) or a dictionary (mapping pin-name to value) of values to be passed to the input pins of the called action. An input value of "Void" ("void" in JavaScript) will be treated like an unconnected pin.

The first variants (without the "into:" argument) return the value of the first output pin (or nil, if there are no output pins). If the output is written multiple times, an error is reported.

The other variant expects a "''funcReceivingValues''" argument, which must be a JS-function or Smalltalk-Block. This function/block is called with the output pin values as arguments. For each pin, one collection containing all values written to the corresponding pin is passed to it as argument (a collection of values is passed, because the pins could be written multiple times by the action).

For example from a Smalltalk coded action, the "<code>Arith [MinMax]</code>" action (which has 2 outputs) can be called with:
self
call:"Arith [ MinMax ]"
with:{ addend1 . addend2 }
into:[:minOutValues :maxOutValues |
"/ ... do something with the min/max values ...
min := minOutValues first.
max := maxOutputValues first.
]
with JavaScript code, the above would be written as:
this.call_with_into("Arith [ MinMax ]",
[ addend1 , addend2 ],
function (minOutValues , maxOutValues) {
// ... do something with the min/max values ...
min = minOutValues.first();
max = maxOutputValues.first();
})
or, using a lambda function, as:
this.call_with_into("Arith [ MinMax ]",
[ addend1 , addend2 ],
(minOutValues , maxOutValues) => {
// ... do something with the min/max values ...
min = minOutValues.first();
max = maxOutputValues.first();
})
In most cases, this callback function would simply store the output values into local variables, as in:
execute
|.. minResult maxResult ..|
...
self
call:'Arith [ MinMax ]' with:#(10 20)
into:[:mins :maxes |
minResult := mins first.
maxResult := maxes first.
].
...
do something with minResult and maxResult
...

Exceptions in the called action can be handled in the calling action:
...
[
result := self call:'Arith [ Quotient ]' with:{ dividend . 0}.
] on:ZeroDivide do:[:ex |
Transcript showCR:'a division by zero occurred'.
].
...

Notice, that a test-fail verdict is reported as TestFail, which is a subclass of Exception,
whereas a test-error verdict is reported as TestError, which is a subclass of Error.
Thus, to handle both failure and error in one handler, you may write:
...
[
result := self call: ...
] on:(Error, Exception) do:[:ex |
Transcript showCR:'either error or fail'.
].
...

or in JS:
...
try {
result = call( ... )
} catch(Error + Exception) {
Transcript.showCR("either error or fail");
}
...

===== Reflection, Information, Queries and Accessing =====

*'''activityCreator''' () The triggering activity (i.e. the caller). Except for special tricks, this is only useful to generate nice print messages (such as "activity foo, called from bar".

*'''activityProcess''' () The thread executing the activity

*'''blockDescription''' () The definition of the activity (i.e. the tree definition item of the action's step)

*'''executor''' () Returns the current executor. See [[#Executor Functions|"Executor Functions"]] below.

*'''inputValueForPin''' (''pin'') The value of a certain pin

*'''inputValueFor''' (''pinName'') The value of a certain pin by name. Reports an error, if there is no such pin, the pin is unconnected or has no value.

*'''inputValueFor_ifAbsent''' (''pinName'', ''ifAbsentValue'') The value of a certain pin by name. Returns "ifAbsentValue" if there is no such pin, the pin is unconnected or has no value.

*'''inventory''' () The inventory of the activity

*'''nameOfStep''' () The name of the corresponding step of the activity

*'''resources''' () All resources which have been acquired for the activity (as specified in the resource-definition of the action). Retrieves a collection of Resource objects, as described below.

*'''resourcesForId''' (''skillId'') Resources which have been acquired for one particular skill-requirement. The argument ''skillId'' corresponds to the name as specified in the first column of the resource definition of the action). Notice, that a collection of Resource objects is returned - even if only one resource has been acquired.

*'''step''' () The corresponding step of the activity

*'''stepLocalStorageAt''' ("<varName>") Retrieves a step's local storage value.

*'''stepLocalStorageAt_put''' ("<varName>", ''value'') Defines a step's local storage value.
:Step local storage can be seen as a kind of static variable, which is only visible inside the code of a single execute function, but with the live time of the step. This means that the value is still present, when the step is executed the next time. However, it will vanish, whenever the diagram which contains the step is edited. Also, its value is not copied, when the step is copied. It is also not made persistent. The value will be reset to nil with every edit operation on the diagram, or via a menu function in the project's "More" menu, or the step's menu.
:Step local storage can be used to count the number of invocations, or to implement static state which is to be preserved between step executions.
:This is an experimental feature, only to be used by advanced users.
 

===== Environment Access =====

Starting at every compound activity, a nested stack of outer environments is present, ending in a top project environment. The following activity methods provide access to some of them. This can be used to automatically setup environment variables from a configuration or when autodetecting a system-under-test's configuration and leaving the values in a defined outer environment. Depending on the intended lifetime of those values, one of the following environments should be chosen as target of such operations:

*'''environment''' () The currently valid environment variables of the compound step which contains this action, or (if none) of the test plan in which this action executes (see "[[#Environment Access|Environment Access]]" below)

*'''environmentAt''' (''anEnvironmentVarName'') The value of an environment variable (in the environment as described above)

*'''environmentAt_put''' (''anEnvironmentVarName'', ''value'') Changing the value of an environment variable (in the environment as describe above)

* '''executorEnvironment''' () an environment which is only present during a single testplan execution

* '''projectEnvironment''' () an environment which is attached to the current test suite (but not persistent when the suite is saved/loaded from an ets file)

* '''browserEnvironment''' () an environment which is attached to the expecco application window; i.e. present while the window is open (i.e. the current session). (it is not made persistent)

* '''systemEnvironment''' () an environment which is present while the expecco application is running (i.e. the current session). (it is not made persistent)

Except for the project environment, none of them are made persistent directly (i.e. the values will not saved with the ".ets"file). However, every test suite, test plan and compound block provides a description of initial values and how to compute them in their environment description, which is edited using the [[ Environment Editor ]] or which can be modified with actions from the reflection library.
Also, such descriptions can be saved and loaded separately from the test suite via the "''Load/Save Parameter Set''" menu functions of the "''File''" menu or via the "--parameters" [[Starting_expecco_via_Command_Line/en#Test_Parameters | command line argument]].

 

===== Event Sending =====
Events can be pushed onto an event queue from either actions found in the standard library or via
API calls to the current activity (also from bridged elementary actions).
The global event handler should be already running (and especially, a handler should be registered) before the first
event is sent. Otherwise, the event might be ignored or an error is raised. A sample suite is found in "demos/d62_Event_Queue_Demos".

* '''pushEvent''' (''eventOrPayloadData'') pushes an event onto the global event handler's event queue. The argument may be either an instance of Event, or the payload (which is packed into an Event instance with type #default). Raises an error, if no global event handler process is running.

* '''pushEventType_data''' (''eventTypeSymbolOrNil'', ''payloadData'') pushes an event of type (or #default) onto the global event handler's event queue. Raises an error, if no global event handler process is running.
 

==== Executor Functions ====

The executor (as returned from the current activity via the "''executor()''" function described above) is responsible
to execute steps in a network and elementary code in a controlled fashion. In addition to sequencing and assigning activities to a particular execution thread, it also cares for the activityLog and error handling.
Usually, you do not need to interact with an executor directly.

*'''executorsWorkingDirectory''' () Temporary working directory. This is removed after the execution (i.e. useful only for very temporary files, which are generated in an action and read in another)

*'''testplan''' () The currently executed testplan (nil if a block test blocks are executed)

*'''project''' () Project (testsuite or library) in which the test is executed
 

==== Resource Functions ====

Resources can be assigned to an action as a "''required resource''", and the execution will be synchronized with the
allocation and reservation of a particular resource as acquired from an inventory.
Once allocated, the resources are available to the action via ''resources()'' or ''resourcesForId()'' functions:

*'''resources''' () retrieves the set of resources allocated for the action. The collection is keyed by the name as given in the "Resources" tab, the associated value is a resource instance providing the concrete values of the resource's skills.

*'''resourceForId''' (idString) retrieves the resource allocated for the idString as given in the "Resources" tab, the returned value is a resource instance providing the concrete values of the resource's skills.

Resource instances respond to the following protocol:

*'''name''' () The name of the resource

*'''skillNamed''' (''nameOrUUID'') Fetch a concrete skill-value of that resource. The argument can be either a skill''s name, or the functional-UUID of the skill element (in the project tree).

*'''skillAttributeNamed''' (''name'') Fetch a concrete skill-attribute-value of the resource
 

==== Test Suite (Project) Functions ====

Every activity, step or action has a reference to its containing project (or library, if imported).
The direct enclosing project/library is returned by the "project()" function, the top level project (i.e. the loaded suite) via the "topProject()" call.
Projects, Test Suites and Libraries are all the same kind of object (i.e. any project can be used as a test suite or imported into another as imported library).

*''aProject''.'''documentation''' () The documentation or nil

*''aProject''.'''functionalId''' () A unique ID which defines this testSuite independent of its name (remains constant after change)

*''aProject''.'''projectsWorkingDirectory''' () Project directory - i.a. all attachments. This directory is created when a project file is loaded and is deleted when expecco is closed. Do not use it for permanently needed files.

*''aProject''.'''modelLanguageStringFor''' (''aString'') translates a string according to the model-language translation table

*''aProject''.'''versionId''' () A unique ID which defines this testSuite in exactly this version. (changed with any edit operation)

*''aProject''.'''elementWithName''' (''aString'') Retrieve an element by name

*''aProject''.'''elementWithId''' (''aUUID'') Retrieve an element by its version id

*''aProject''.'''elementWithFunctionalId''' (''aUUID'') Retrieve an element by its functional id

*''aProject''.'''typeNamed''' (''aTypeName'') Retrieve a datatype. To instantiate a type, write "<code>(self project typeNamed:'Foo') new</code>".
 

==== Testplan Functions ====

*''aTestPlan''.'''documentation''' () The documentation or nil

*''aTestPlan''.'''name''' () The name of the Testplan

*''aTestPlan''.'''tags''' () A collection of tags of the testplan

*''aTestPlan''.'''functionalId''' () A unique ID which defines this testplan independent of its name (remains constant after change)

*''aTestPlan''.'''versionId''' () A unique ID which defines this testplan in exactly this version. (changed with any edit operation)
 

==== Step Functions ====

*''aStep''.'''name''' () The name of the Step

*''aStep''.'''tags''' () A collection of tags of the Step

*''aStep''.'''inputPins'''() A collection with all input pins

*''aStep''.'''inputPinForPinName'''(''inputPinName'') The corresponding input pin. Raises an error, if no such input pin exists.

*''aStep''.'''inputPinForPinName_ifAbsent'''(''inputPinName'', ''ifAbsentValue'') The corresponding input pin. Returns ''ifAbsentValue'', if no such input pin exists.

*''aStep''.'''outputPins'''() A collection with all output pins

*''aStep''.'''outputPinForPinName'''(''outputPinName'') The corresponding output pin. Raises an error, if no such output pin exists.

*''aStep''.'''outputPinForPinName_ifAbsent'''(''outputPinName'', ''ifAbsentValue'') The corresponding output pin. Returns ''ifAbsentValue'', if no such output pin exists.
 

==== Pin Functions ====

The input and output pins can be referenced in elementary code directly by their name.
The name refers to the pin - '''NOT''' the passed value (this allows for the code to check, if a value is present). For indexed pins (i.e. in steps with a variable number of pins), the collection of pins is referred to by the name, and pins are accessed via an index (1..). See more about variable pins in the section below.

===== Common to all Pins: =====
*''pinName''.'''datatype''' () Returns the data type of the pin (Reflection-API)

===== Input Pins: =====

*''pinName''.'''hasValue''' () Returns true if the pin has received a value (useful to determine if there is a value if the trigger condition is "AndConnected" or "Or")

*''pinName''.'''hasEnvironmentFreezeValue''' () Returns true if the pin has a freezeValue from an environment

*''pinName''.'''hasFreezeValue''' () Returns true if the pin has a freezeValue

*''pinName''.'''isConnected''' () Returns true if the pin is connected (but not frozen)

*''pinName''.'''value''' () Returns the value of the pin. This is either the value received via a connection, or a constant freeze value, or an environment variable freeze value. Raises an error if the pin did not receive any value.

*''pinName''.'''valueIfPresent''' () Returns the value of a pin or nil if the pin did not receive any value. Similar to "<code>value()</code>", but avoids the exception.

*''pinName''.'''valueIfAbsent''' (''alternativeValue'') Returns the value of a pin or the alternativeValue, if the pin did not receive any value. Similar to "<code>value()</code>", but avoids the exception.

*''mbxPinName''.'''waitForValue''' () - ''Mailbox pins only'' The pin has to be a mailbox pin. The execution of this action will be suspended until the pin receives a value.

*''mbxPinName''.'''waitForValueWithTimeout''' (''seconds'') - ''Mailbox pins only'' Like above, but the execution will only wait for the specified time limit, given in seconds. The parameter is typically an integer, but can also be a fraction (e.g. 1/3) or a floating-point number (e.g. 0.3).

*''mbxPinName''.'''consumeValue''' () - ''Mailbox pins only'' Consumes the current value which is present at the mailbox input pin. If there is another pending input value, <code>hasValue()</code> will continue to return true, and <code>value()</code> will return the next pending value.

===== Output Pins: =====

*''outPinName''.'''isBuffered''' () True if the pin is buffered (only generates a value if the action completes successful)

*''outPinName''.'''isConnected''' () Returns true if the pin is connected. This can be used to not perform expensive computations in an elementary action, iff no-one is interested in that value.

*''outPinName''.'''value''' (''data'' ) Writes the value. If the output pin is unbuffered and connected to another step's input pin, the other step's action may be triggered (if the other step's trigger condition is fulfilled). If the output pin is buffered, the datum will be passed to the connected input, when the action has finished with success.

===== Variable Input Pins =====

Elementary steps can have a variable number of input pins, if the pin's schema has the "variable pin" attribute set. To change the number of pins of a step in the diagram editor, pull the pin-handle of a placed step, to add or remove pins. In elementary code, the following API call entries (to the variable pin) are provided to deal with this situation:

*''pinName'' now refers to a collection of pins, representing the set of pins actually present at the step. In contrast to regular pins, where pinName refers to a single pin.

*''varPinName''.'''numberOfVariablePins''' () returns the number of actual pins present in the step for the (variable) schema pin named "pinName"

*''varPinName''.'''size''' () same as the above "numberOfVariablePins"

*''varPinName''.'''inputPinAt''' (''idx'') returns the idx'th actual pin of the schema pin named "pinName". Notice this retrieves the pin for reflection queries, NOT the pin value. To get value or query if it has a value, call ''valueAt:''() / ''hasValueAt''(). Pin indexing starts with 1.

*''varPinName''.'''at''' (''idx'') same as inputPinAt(''idx'')

*''varPinName''.'''hasValueAt''' (''idx'') true if the idx'th variable pin is connected and has received a value. Same as <code>hasValue()</code> for variable input pins. Indices start with 1.

*''varPinName''.'''values''' () Retrieves the values passed to the pins as an array. The array contains nil entries for disconnected pins and those without a value

*''varPinName''.'''valuesPresent''' () Retrieves the values as present; skips unconnected pins or those without a value.

*''varPinName''.'''valueAt''' (''idx'') to get the idx'th pin's value; raises an error if no value was given or pin is not connected. Same as <code>value()</code> for variable input pins.

*''varPinName''.'''valueIfPresentAt''' (''idx'') to get the idx'th pin's value, or nil if no value was given or pin is not connected

*''varMbxPinName''.'''waitForValueAt''' (''index'') -''Variable mailbox pins only'' Same as <code>waitForValue()</code> for variable input mailbox pins.

*''varMbxPinName''.'''waitForValueAt_withTimeout''' (''index'', ''seconds'') - ''Variable mailbox pins only'' Same as <code>waitForValue()</code> for variable input mailbox pins.

*''varMbxPinName''.'''consumeValueAt''' (''index'') - ''Variable mailbox pins only'' Same as <code>consumeValue()</code> for variable input mailbox pins.

===== Variable Output Pins =====

Starting with expecco v2.1, steps can also have a variable number of output pins, if the schema has the "variable output pin" attribute set. To change the number of pins, pull the pin-handle of a placed step, to add or remove pins. In elementary code, the following API call entries (to the variable pin) are provided to deal with this situation:

*''varPinName''.'''numberOfVariablePins''' () returns the number of actual pins present in the step for the (variable) schema pin named "pinName".

*''varPinName''.'''outputPinAt_value''' (''idx'', ''value'') write a value to the idx'th output pin. Index starts with 1.

*''varPinName''.'''outputPinAt''' (''idx'') returns the idx'th actual pin of the schema pin named "pinName". Notice that this retrieves the pin; to write an output value to it, call ''value''(v) on the returned pin.

*''varPinName''.'''at''' (''idx'') same as outputPinAt(''idx'')

*''varPinName''.'''outputPins''' () returns a collection of all actual pins present in the step for the (variable) schema pin named "pinName".

 

==== Datatype Functions ====

A datatype can be retrieved by asking a pin for its datatype using the '''datatype''' () function.
This is sometimes useful in elementary code, in order to instantiate a new value (given the pin) or to ask for details of the type.

*''aType''.'''name''' () The name of the Datatype

*''aType''.'''isAnyType''' () true if the datatype is the builtin "Any" type

*''aType''.'''isArrayType''' () true if the datatype is an "Array" type (with any element type)

*''aType''.'''isCompoundType''' () true if the datatype is a compound (structure) type

*''aType''.'''isEnumType''' () true if the datatype is an enumeration type

*''aType''.'''isPrimaryType''' () true if the datatype is any builtin primary type

*''aType''.'''isRangeType''' () true if the datatype is a subrange of another type

*''aType''.'''isTupleType''' () true if the datatype is a tuple type

*''aType''.'''isUnionType''' () true if the datatype is a union type

*''aType''.'''isStringPrimaryType''' () true if the datatype is the builtin "String" primary type

==== Enum Type Functions ====

*''anEnumType''.'''values''' () returns an array of enum-value names (symbolic)

*''anEnumType''.'''integerValueOf''' (''elementName'') returns the associated integer value.

==== Compound Type Functions ====

*''aCompoundType''.'''namedFieldDescriptions''' () returns an array of descriptions of the named fields (if any)

*''aCompoundType''.'''indexedFieldDescriptins''' () returns a description of indexed fields (if any)

Each field description can be asked for the "fieldName()", "fieldType()" and "defaultValue()".

==== Primary Type Functions ====

*''aPrimaryType''.'''typeClass''' () returns the underlying Smalltalk class, of which values are instances of.

==== Range Type Functions ====

*''aRangeType''.'''baseType''' () returns the underlying base type. Typically this will be the Integer primary type.

*''aRangeType''.'''minValue''' () returns the minimum value of the range

*''aRangeType''.'''maxValue''' () returns the maximum value of the range
 

==== Functions for Any Tree- or Diagram Element ====

These include: BlockDescriptions, Types, TestPlans, TestCases, Steps, Connections, Pins, Annotations etc.

*''object''.'''versionId''' A globally unique identifier (GUID or UUID) which is changed with every modification of the item

*''object''.'''functionalId''' A globally unique identifier (GUID or UUID) which is assigned once-and-for-all to the item

*''object''.'''id''' alias for versionId().

*''object''.'''tags''' A collection of tags.

*''object''.'''isAnnotation''' true, if it is an annotation (in a diagram)

*''object''.'''isStep''' true, if it is a step (in a diagram)

*''object''.'''isConnection''' true, if it is a connection (in a diagram)

*''object''.'''isBlockDescription''' true, if it is a block description (in the tree)

*''object''.'''isAttachment''' true, if it is any attachment (in the tree)

*''object''.'''isFileAttachment''' true, if it is a file attachment (in the tree)

*''object''.'''taggedValueAt''' (''aKey'') To retrieve a tagged value. These are usually preserved when objects are transported to/from other systems.

*''object''.'''taggedValueAt_put''' (''aKey'', ''anObject'') to change a tagged value. Only a limited set of datatypes are supported: anObject must be a '''String''' or a '''Number'''.

*''object''.'''propertyAt''' (''aKey'') to retrieve an expecco property. These are expecco-internal properties. These are usually not recognized by other systems.

*''object''.'''propertyAt_put''' (''aKey'', ''anObject'') to set an expecco property. These are usually not recognized by other systems. Only a limited set of datatypes are supported: anObject must be a '''String''' or a '''Number'''.
 

== Groovy Elementary Blocks ==

Groovy is an open source interpreter and compiler for a Java like scripting language which runs on top of the Java Virtual machine. For details, visit [http://groovy-lang.org/ "groovy-lang.org"] and especially the [http://groovy-lang.org/documentation.html Groovy Documentation Portal].

Code written as a Groovy elementary block is not executed directly by expecco. Instead, the code is forwarded to a Groovy shell which runs inside a Java Virtual Machine (JVM). This may be a local JVM, whose sole purpose is to provide additional utility functions or which provides an interface to the actual system under test (SUT), or it may be the JVM which executes the tested application and is running physically on the SUT.

By using Groovy blocks, expecco's basic black-box test functionality is extended to include powerful gray- and white-box tests. You can access the internals of objects inside the SUT, call its functions and even define new classes and functions and call them. Groovy is especially useful, if you have to install callback- or hooks inside the SUT, which interact back to expecco (e.g. to collect SUT-internal events and allow expecco to read those from the SUT). However, you should keep in mind that your tests may become affected by changes in the SUT and needs to be modified if interfaces change (which is a general property of white box tests, not a limitation of expecco).

The machinery to interact with a JVM (and therefore to execute Groovy code blocks) requires the Java Bridge plugin, which is now (rel18.1) part of the basic expecco package. Groovy itself is available for free as a jar class library, which is loaded with or into the target application. The Java Bridge plugin already includes a prepackaged Groovy interpreter which can be loaded transparently into the SUT application whenever a Groovy block is executed. So except for the setting of the JVM path, no further setup or installation is required.

=== Why use Groovy Elementary Blocks? ===
The Java Bridge and especially Groovy code is very useful when testing GUI frameworks, communication protocols or machine control soft- and hardware which is written in Java. Especially, if you have to call functions internal to the SUT in order to trigger actions or if you need to be informed about state changes via listeners or callbacks, Groovy is the perfect tool for the task. Note that calls into the JVM are relatively straight forward, using the method forwarding mechanism, even from Smalltalk code. However, callbacks and listeners, which usually have to be implemented as instances of special derived classes of a an abstract framework class, are hard to realize without Groovy.

Without Groovy, you would have to add such classes to the software inside the SUT - e.g. by adding them to the tested software's jar packages, or by adding extra jar packages. In addition, you'd have to provide a communication mechanism (socket, pipe or file interchange), by which your test action is able to retrieve this information.

=== What is the Difference between a regular (expecco-) JavaScript Block and a Groovy Block? ===

In one sentence: expecco JavaScript actions are executed inside expecco, Groovy actions inside the SUT (System Under Test) or any other external JVM (Java Virtual Machine).

More detailed:

Expecco's JavaScript actions are actually alternative syntactic forms of Smalltalk actions. When executed, they run inside the expecco executable and have access to any class or object inside expecco itself, or those which are passed in via input pins or environment variables.

On the other hand, Groovy actions are "''injected''" (eg. downloaded) into a Java VM and execute in that object space. They cannot directly access expecco classes or objects, but instead can access all public classes and objects within the JVM in which they run, which can be the SUT (System Under Test). By means of proxy objects (which are forwarding operation-calls), expecco can deal with remote objects almost transparently: these can be returned from a Groovy action to expecco, and later be used again as arguments to other Groovy actions; i.e. they can be passed around via output- and input pins, stored in variables and inspected.

=== What is the Difference between a Groovy Block and a Bridged Node Block? ===

Groovy blocks execute inside a JVM (Java Virtual Machine) and can access any Java code (eg. classes inside a java application or inside a dynamically loaded jar-library).

In contrast, Node actions are executed inside a Node (aka "Node.js") interpreter (which is not a JVM).

There are also slight differences in the syntax: Groovy is more Java-like, whereas Node blocks use pure JavaScript.

=== Groovy Compilation Mechanism and Performance Issues ===
When a Groovy action is executed for the very first time, the block's code is transmitted via the bridge to the Groovy shell on the target JVM as a string. There, the code is parsed and an anonymous jar is created, containing Java byte code. Thus, there is some initial overhead involved in both sending the code and more so in compiling the code in the JVM. However, for every followup call, the JVM will directly call the generated code and run at full Java speed (i.e. the execution speed is almost as if native Java code was executed), although there is still some overhead due to the interprocess communication (typically a few milliseconds for every call)

=== Using a Single Local JVM Connection / Executing Groovy Actions on the Local Machine ===
By default, a Groovy action is executed on a JVM which runs on the local machine; i.e. the machine on which expecco itself is running.
With the execution of the very first Groovy action, a JVM is started as defined in the expecco settings dialog, then a bridge connection is established to that JVM, and the Groovy interpreter (called "''GroovyShell''") is loaded and instantiated on the JVM. Then a reference to that GroovyShell object is remembered and used for all followup Groovy actions which are to execute on that local JVM.
This default behavior is convenient if you want to use Java support libraries for reporting, statistics or other computations, or if your SUT is running inside a local JVM, or if you want to call interface functions (protocols) which actually talk to your SUT.

=== Using a Particular JVM Connection / Executing Groovy on a Possibly Remote Machine ===
If you either need to customize the JVM startup and/or your test scenario has to talk to one or multiple remote systems (or multiple java programs within one scenario), you have to setup multiple java connections, and pass the connection to use to your Groovy actions.
This can be done either via an input pin, or via an expecco environment variable.
The algorithm to provide this is as follows:

* if the action has a pin named "<code>groovy</code>", and it is connected, that pin's value is used as GroovyShell handle
* otherwise, if the environment contains a variable named "<code>GROOVY</code>", that variable's value is used
* otherwise, a new GroovyShell is instantiated and used, on the JVM which is given by:
** if the action has a pin named "<code>java</code>", and it is connected, that pin's value is used as Java Bridge handle
** otherwise, if the environment contains a variable named "<code>JAVA</code>", that variable's value is used
** finally, otherwise a local JVM connection is used (a shared singleton connection).

This scheme makes the most common case easy, where only one single local JVM is required,
but still allows the flexibility to handle multiple JVMs and even multiple different GroovyShell instances within each JVM.

To use input pins, you have to create corresponding pins manually, and the pin names MUST be "java" / "groovy".
You cannot use these two reserved names as regular input pin names.

=== Choosing another JVM Version ===
By default, the Groovy interpreter runs in the default Java virtual machine. That is the JWM which would be executed when
entering "<CODE>java</CODE>" on the command line. To verify the version, open a command shell (or cmd.exe window) and enter
java -version

To specify another JVM, go to "''Extras''" → "''Settings''" → "''Plugins''" → "''Java Bridge''",
and enter the path to a JRE (Java Runtime Environment) folder into the "''Java Installation Path''" field.
You can also enter a JDK (Java Development Kit) folder name into that field. See also [[Settings_JavaBridgeSettings]].

=== Additional JAR Class Libraries ===
By default, the Groovy code runs inside a JVM which has its classPath initialized from the preferences.
These class path preferences can be changed in the "''Settings''" → "''Project Management''" → "''Groovy Class Path''" settings dialog.
Additional jars can be added to the common classPath (before a JVM is started) by the "[''Add JAR to Groovy Class Path'']" action,
or dynamically to a concrete already running JVM instance via the "[''Add JAR to JVM'']" action.

Notice that you have to restart existing groovy connections to make such changes effective (via the "''Extras''" → "''Debugging''" → "''Shut Down Bridge Connections''" menu function).

=== Groovy Code Snippets / Examples ===
==== Calling Existing Code in the System Under Test (SUT) via a Groovy Action====

A Groovy block's code looks very similar to a regular JavaScript block's code (with some differences in the Groovy language).
However, it is executed inside a JVM, which may be inside the SUT.
It can therefore instantiate Java objects and call static and member functions inside the target system, if it is programmed in Java.

For example, too call a static function named "''foo''" in a class named "''MyTestClass''", use the following Groovy block:

def execute() {
MyTestClass.foo("hello world");
}

if the class is located in another package (or especially: in one of your own),
use explicit package prefixes:
def execute() {
javax.swing.JFrame frame = new javax.swing.JFrame();
javax.swing.JButton button = new javax.swing.JButton( "Press Me" );

frame.add(button);
frame.setSize(300,100);
frame.setVisible(true);
}
or an import declaration:

import javax.swing.*;

// end of import definitions

def execute() {
JFrame frame = new JFrame();
JButton button = new JButton( "Press Me" );

frame.add(button);
frame.setSize(300,100);
frame.setVisible(true);
}
Notice that you may not remove the comment line starting with "// end of....".
 This separator pattern has been hardcoded into the Groovy machinery to separate any class and import
definitions from the execution method.

==== Defining a New Class in the System Under Test using Groovy ====
[[Bild:Groovy_Defining_Class1.png|thumb|300px|Drag this image into expecco]]
You can define your own classes in a Groovy block:

For demonstration, let's start with a simple running example:
class TestSleep {
static void main(String[] args) {
println 'Step 1'
sleep(1000)
println 'Step 2'
sleep(1000)
println 'Step 3'
}
}

// end of definitions -- do not remove this line unless imports above is empty

def execute() {
TestSleep.main(null);
}

Instances of new classes may be required especially to install listeners and callbacks when testing UI or server applications. A typical scenario is when you want expecco to be informed about mouse or keyboard events (MouseListener).

Usually, instances of such classes are created in one Groovy action,
and passed to expecco via an output pin:

class MyClass extends Object {
Object someState;

def set_someState(Object newValue) {
someState = newValue;
}
def get_someState() {
return someState;
}
def String toString() {
return "a very\nlong\nmultiline\na\nb\nstring\n";
}
}

// end of local definitions

def execute() {
outputPin.value( new MyClass() );
}

Then, additional Groovy actions take that as an input value and call the classes methods:
def execute() {
Object myInst = inputPin.value();

myInst.setSomeState(123);
}

or:
def execute() {
Object myInst = inputPin.value();

output.value( myInst.getSomeState() );
}

==== Defining a Listener Class in the System Under Test using Groovy ====
A common pattern in Java communication frameworks is to define an abstract classes or interfaces which has to be subclassed by users of the framework. This pattern is common for callbacks or event listeners. The programmer has to define a listener class, create an instance of it, and register it towards the communication framework. To interact with such a framework in expecco, you will need a listener class, which responds to callbacks from the framework and either remembers them for later queries from a testcase's activity, or by directly calling back into expecco. The later is much harder to deal with, as those callbacks may come at any time, even when the test has already finished or the test is being debugged (remember that the JVM may run independent from expecco). So synchronization issues may be hard to solve. It is much easier and recommended to implement the first approach: the listener collects incoming events, until expecco is ready to process them.

You will need an elementary Groovy block to instantiate and register the listener towards the framework similar to the conceptual code below:
// a Groovy Elementary Block

import <interface or abstract class from which to inherit>;

class MyListener extends AbstractListener {
ArrayList eventQueue = new ArrayList();
Object eventNotifier = new Object();

/**
 * Called from a framework when an event occurs.
 */
public void onExampleEvent(Object event) {
synchronized (eventQueue) {
eventQueue.add(event);
}
synchronized (eventNotifier) {
eventNotifier.notifyAll();
}
}

/**
 * Called from expecco to fetch next event.
 *
 * Of there is no event in the queue, blocks
 * until an event arrives (by means of #onExampleEvent())
 */
public Object getNextEvent() {
while (true) {
synchronized (eventQueue) {
if (! eventQueue.isEmpty()) {
return eventQueue.remove(0);
}
}
synchronized (eventNotifier) {
try {
eventNotifier.wait();
} catch (InterruptedException ie) {
// Pass, try again
}
}
}
}
}

// end of local definitions

// called from expecco, to instantiate a listener
def execute() {
var theListener = new MyListener();

framework.registerListener ( theListener );
outputPin.value( theListener ); // return it to expecco
}

Make sure that the above elementary code is called from your activity diagram in the initialization/setup phase, and that the returned listener reference is either remembered in an environment variable of your suite, or passed down to the actual test case via input/output pins.

Define an additional elementary block (here in JavaScript, but could also be Smalltalk or Groovy), which takes the listener as input pin and fetches the next event via <code>getNextEvent()</code>:

// a JavaScript Elementary Block

execute() {
var theListener;
var event;

theListener = inPin.value();
event = theListener.getNextEvent();
outpin.value ( event );
}
The above code blocks the test suite until an event arrives. It may be useful to add another method to query the number of received events, or to flush any previously received and already enqueued events.

In your test case, perform any stimulation required to make the framework generate an event, so that the listener's framework entry is called.
Then, invoke the #getNextEvent() action to suspend execution until an incoming event arrives (you will probably set a [[DiagramElements-Pin#Timelimit Input Pin|time limit]] on that step's execution). Once this action finishes, the event is available in expecco as a reference to the real event object (remember: the event object is an object inside the remote Java machine, so what you have in expecco is a handle to that remote object).

All getters, setters and other methods of the event's implementation can be invoked from elementary code (any of the programming languages can do that, due to the message forwarding of the bridge).

For example, assuming that the event provides getEventID() and getMessageString() getters,
which can be called from a Smalltalk action with:
id := theEvent getEventID. msg := theEvent getMessageString.
and from a JavaScript action or from another Groovy action witht:
id = theEvent.getEventID(); msg = theEvent.getMessageString();.

Also, the expecco object inspector has been enhanced to recognize those proxy bridge objects, and presents the internal state, inheritance and class protocol in a multitab fashion. This makes looking into those remote objects almost as comfortable as looking into local ones.

==== Accessing JMX MBeans ====

import java.lang.management.*

// end of definitions

def execute() {
def os = ManagementFactory.operatingSytemMXBean;
def mem = ManagementFactory.memoryMXBean;

Transcript.showCR("OS architecture: " + os.arch.toString() );
Transcript.showCR("MEM heapUsage : " + mem.heapMemoryUsage.toString() );
Transcript.showCR("POOLS:");
ManagementFactory.memoryPoolMXBeans.each { eachPool ->
Transcript.showCR(" pool name : " + eachPool.name.toString() );
Transcript.showCR(" pool peakUsage: " + eachPool.peakUsage.toString() );
}
}
Please refer to the corresponding Java documentation for details.

==== Executing Jython, JRuby or other Script Code inside the JVM ====

[[Datei:bulb.png|16px]] the following example is somewhat outdated due to the new builtin support for jython (in 19.2).

The following example executes Jython (Python) code inside the JVM (please make sure that the jython jar is in your Groovy class path):
import org.python.util.PythonInterpreter;
import org.python.core.*;

// end of definitions -- do not remove this line unless imports above is empty

def main()
throws PyException
{
Properties p = new Properties();
// p.setProperty("sys.path", "/Users/cg/work/exept/bridgeFramework/javaBridge/javaBin/jython2.7.0");

p.setProperty("python.path", "<path to jython2.7.0/Lib>");
p.setProperty("python.home", "<jython2.7.0>");

Object props = System.getProperties();
// String[] args = new String[0];
String[] args = { "" };
PythonInterpreter.initialize(props, p, args);

PythonInterpreter interp =
new PythonInterpreter();

System.out.println("Hello, brave new world");
interp.exec("import sys");
interp.exec("print sys");

interp.set("a", new PyInteger(42));
interp.exec("print a");
interp.exec("x = 2+2");
PyObject x = interp.get("x");

System.out.println("x: "+x);
System.out.println("Goodbye, cruel world");
}

def execute() {
main();
}
Of course, you can also write the "interp" instance to an output pin, and remember it somewhere or pass it to other actions. Then, other actions can directly invoke the "exec(...)" function, without instantiating a new interpreter.

=== Groovy Datatype Limitations ===

==== Integer types ====
As Groovy dynamically compiles to plain Java bytecode and executes on top of a regular JVM, the integer range is limited to 32bit (64bit for "long int" types).
No automatic conversion between small and large integers is performed. If required, you will have to use a BigNum package and/or cast int to long int. There is currently no automatic conversion or transparent support to pass large numbers from expecco to Groovy and vice versa. Integers passed from Java to expecco will be represented as instances of the Integer type there.

==== Limited Object Conversion to/from Groovy ====
Some limited form of object conversion is automatically performed when passing expecco's Smalltalk objects to Groovy, and back when returning values from Groovy. This conversion especially affects values passed to/from pins of a Groovy action.

The following table summarizes the conversion process:
{| Border
! from Smalltalk
! to Java and from Java
! to Smalltalk
!
|-
| String
| String
| String
|-
| Integer (up to 32/64 bit)
| int, long int, boxed Integer
| Integer
|-
| Float, Double
| float, double; boxed or unboxed
| Float (Notice that Smalltalk Floats have double precision)
|-
| Fraction
| float, double; boxed or unboxed (danger alert: precision may be lost)
| Float (Notice that Smalltalk Floats have double precision)
|-
| Boolean
| Boolean
| Boolean
|-
| Array of any above
| ArrayList of any above
| Array of any above
|-
| other Smalltalk Object(!)
| -
| -
|}

(!) does not work, yet: at the time of writing, Smalltalk objects other than the basic types listed above cannot be passed to Java.
However, the reverse direction is possible, and Smalltalk includes a mechanisms to handle (and even inspect) remote Java objects.

==== No Smalltalk Classes, No Smalltalk Objects in Groovy ====
Of course, no Smalltalk class can be used directly in Groovy code.
And Smalltalk objects can only be passed as opaque handles to/from Groovy as described above.
However, all Java classes are at your hands now!
Some limited interaction with expecco and underlying Smalltalk objects is possible via the "<code>eval()</code>" and "<code>perform()</code>" API described below.

However, in general: if more complex objects need to be interchanged, this must be either done by converting them to an array (of objects), possibly an array of arrays, which is passed to a Groovy "interface function" first, which instantiates the required Java object(s). Or, alternatively to some ASCII representation (XML or JSON, for a more lightweight approach) and convert this back and forth.

=== Handling of Java (and Groovy) Objects in expecco/Smalltalk ===

==== Java Object References (Handles) ====

Groovy elementary function can return references to Java objects via output pins. Because the actual object is located inside a JVM (i.e. outside of expecco), these references are treated like opaque handles by the underlying Smalltalk runtime system. However, a mechanism is provided to allow for almost transparent access to the referenced object's private slots, its classes' static slots, its class hierarchy and method information. The object inspector is able to present that information in a convenient way, similar to how Smalltalk objects are presented. Also methods of the Java object can be called and values returned to expecco.

==== Message Forwarding ====

Smalltalk and JavaScript code can send regular messages to Java objects inside a remote JVM. This is possible via the Smalltalk "<code>doesNotUnderstand:</code>" mechanism, which intercepts any call, sends a message to the real object (via the Java Bridge), awaits an answer and returns the result, which is usually a reference to another Java object.

All of this is transparent to the programmer of the elementary code, except for the fact that Java method naming is different from Smalltalk. And of course a performance penalty, due to the interprocess communication, marshalling overhead and dynamic lookup via reflection on the Java side.

==== Method Name Conversions ====

When a message is sent from Smalltalk code to a Java object, a message translation mechanism similar to the Smalltalk <-> JavaScript mechanism is used:
foo -> foo()
foo:arg -> foo(arg)
foo:a1 _:a2 ... _:aN -> foo(a1, a2, ... aN) where the "_" are arbitrary strings.

thus, to call a Java object's "installHandler(arg1, arg2, arg3)" function, you should write in Smalltalk:
javaObject installHandler:arg1 _:arg2 _:arg3
and in JavaScript:
javaObject.installhandler(arg1, arg2, arg3)

It is obvious, that this kind of code is better written in JavaScript, being the same as a native Java call would look like.

==== Conversion of Dynamic Smalltalk Objects to Static Java Types ====

Inside expecco (which is running under a Smalltalk VM), all object references are dynamically typed.
This means, that in Smalltalk, every object holds a reference to its class and in principle, any object can be passed as argument to
a called function.
In contrast, Java requires the type of a function argument to be declared (either as a class or interface),
and the argument type(s) are part of a method's signature.

Therefore, when calling a Java function from Smalltalk, the correct function must be found by reflection at execution time.

For example, if the Java object provides two methods as in:

public void foo(Integer arg) { ... }

public void foo(Float arg) { ... }

and it is called from Smalltalk with:

aJavaObjectHandle foo: 1

then the "Integer"-argument version of foo must be called.

Whereas if called as:

aJavaObjectHandle foo: 1.0

then the "Float"-argument version is to be called.

For this, the Java Bridge side uses reflection to scan the available methods for a best fit,
and transforms the passed Smalltalk argument to the best matching type before calling the actual function.

There are some rare situations, where this automatic lookup fails or finds a wrong method.
For example, if same-named functions exist with
both a "<code>float</code>" (unboxed) and a "<code>Float</code>" (boxed) argument,
and you need to make sure which is called.
In such cases, you can either use a Groovy block as mediator, which calls the desired function with an explicitly casted argument, and call the Groovy block from Smalltalk (or JavaScript) or use an explicit cast operation ("<code>Bridge2::Cast object:o as:typeName</code>").

==== Current IDE Limitations ====

The Smalltalk IDE has currently only limited support to extract and present Java's static type information. Currently, there is no class- and function name completion in the editor, making elementary code development for Java/Groovy less pleasant. Therefore, for complicated setups, it is a good idea to open a specialized Java development environment (e.g. eclipse) in parallel, and test the setup code there before copy-pasting it into a Groovy block.

Eclipse is also useful to find out class- and method names during development.

=== Groovy Code API ===

Groovy code supports a '''subset''' of the above activity functions, which is intended provide an interface similar to the JavaScript and Smalltalk elementary code API. Of course, technically for every API function below, the elementary code executing in the remote Java VM has to make a remote procedure call back to expecco. On the JVM side, this is done very similar to the above described remote message mechanism, when messages are sent from Smalltalk to Java/Groovy. However, due to the static type system, it is not possible to call previously unknown interfaces. Therefore, only a fixed set of API entry points is supported.

==== Attention / Warning (Groovy) ====

Unless explicitly prevented by the "<code>mayStillDoExpeccoCalls()</code>" function ([[#Special_Functions (Groovy) |described below]]),
all called expecco functions listed below will ONLY work as expected WHILE the Groovy action is still ACTIVE (i.e. while inside the Groovy "<code>execute()</code>" function).

The reason is that expecco ensures that handlers, which are responsible for transferring information from the Groovy code back to expecco,
will always be released, when the Groovy step has finished its execution.
This is mostly required to prevent memory leaks in the Java VM, because the observer instance object is registered inside the JVM and would remain there forever, if not unregistered. This observer object is a proxy for Java code, which implements all the functions below and forwards them (via an IPC mechanism) to expecco. One new such object is required for every Groovy action execution and if not released, they sooner or later consume huge amounts of JVM memory. Therefore by default, the observer is released after the Groovy action execution.

In most Groovy blocks this is not a problem, except for those which install callback methods,
AND those callbacks get called AFTER the Groovy block has finished (for example by another Java thread),
AND the callback code calls one of those expecco interface functions. This includes the Transcript output functions, notifications and pin value writers.

Unless the observer is still around, callbacks are ignored and behave like a no-operation, if called after the step has finished.
Of course, writing to a pin from within a callback AFTER the execute() function has finished does not work in any case (with or without a kept observer). The behavior in this case is undefined; currently, it is a no-operation, but it may be changed to raise an error in future versions.

==== The Current Activity (Groovy) ====
The current activity instance is accessed as "''this''" inside the Groovy action code (like in an elementary JavaScript block). For every executed action, a new activity object is instantiated. It is usually alive during the execution only (i.e. it is destroyed and its memory reused automatically, after the block's action has finished).

In Groovy (as in JavaScript or Java), if no receiver is given for a function call, "''this''" is the implicit receiver. Thus the statements "<CODE>this.logInfo("hello")</CODE>" and "<CODE>logInfo("hello")</CODE>" are equivalent.

==== Objects are passed by Reference ====
Except for Strings and Numbers, objects are passed from Groovy to expecco by reference. These references can later be sent back to other Groovy actions transparently. Notice, that these references will keep the Groovy object (which is actually a Java object) alive until the reference object is garbage collected in expecco. Be aware that such references may have a very long life time, if kept in an activity log. Therefore, output pins which receive such references should either be marked as non-logging, or you should set the "''Log Strings of Bridge Objects''" flag in the [[Settings_LoggingSettings/en||"''Settings''" - "''Execution''" - "''Logging''" dialog]].

==== Reporting (Groovy) ====

*'''error''' () Report a defect (in the test). Stops execution.

*'''error''' (''infoString'') Report a defect (in the test). Stops execution. The infoString argument will be shown in the activity log.

*'''fail''' ([''infoString'']) Report a failure (in the SUT) with optional infoString. Stops execution.

*'''inconclusive''' ([''infoString'']) Report an inconclusive test (with optional infoString). Stops execution.

*'''activitySuccess''' ([''infoString'']) Finishes the current activity with success.

*'''pass''' ([''infoString'']) Finishes the current testCase with success. The optional infoString argument will be shown in the activity log.

*'''testPass''' ([''infoString'']) Same as pass(); for compatibility with bridged languages where "pass" is a reserved keyword (i.e. python).
 

==== Logging (Groovy) ====

*'''logError''' (''messageString'') Adds a error message to the activity log.

*'''logError''' (''messageString'', ''detail'') Adds a error message to the activity log.

*'''logWarning''' (''messageString'') Adds a warning to the activity log.

*'''logWarning''' (''messageString'', ''detail'') Adds a warning to the activity log.

*'''logInfo''' (''messageString'') Adds an info message to the activity log.

*'''logInfo''' (''messageString'', detail) Adds an info message to the activity log.

*'''alert''' (''messageString'') Adds a warning message to the activity log, and also shows a DialogBox, which has to be confirmed by the operator. The dialog box and confirmation can be disabled by a settings flag in the "[[Settings_LoggingSettings/en|Execution-Log-Settings]]" dialog (by default it is disabled).

*'''warn''' (''messageString'') Same as ''alert()'' (for Smalltalk protocol compatibility).
 

==== Reflection, Information, Queries and Accessing (Groovy) ====

*'''environmentAt''' (''anEnvironmentVarName'') The value of an environment variable

*'''environmentAt_put''' (''anEnvironmentVarName'', ''value'') Changing the value of an environment variable.

*'''nameOfActiveTestPlan''' () The name of the currently executing text plan

*'''nameOfActiveTestPlanItem''' () The name of the currently executing text case

*'''nameOfStep''' () The name of the corresponding step of the activity
 

==== Interaction with Expecco and Debugging (Groovy) ====

*'''eval''' (''smalltalkCodeString'') Evaluate a piece of Smalltalk code inside expecco.

*'''evalJS''' (''javascriptCodeString'') Evaluate a piece of JavaScript code inside expecco.

*'''inspect''' (''javaObject'') Opens the expecco-inspector showing details of the argument object.

*'''halt'''() or '''halt'''(''message'') stops (breakpoint) and opens the expecco-debugger; however, this debugger cannot show the internals of the suspended Groovy code, but will only present the expecco calling chain up to the bridge call.

 

==== Special Functions (Groovy) ====

*'''mayStillDoExpeccoCalls''' (''boolean'') Ensures that the API-functions described here will still be callable (by Java callback functions from other threads) even after the step has finished execution. In other words, it prevents releasing the observer object which is responsible for the transfer of information between the two systems. Be aware that this object remains and will never be released, until the bridge connection is closed. I.e. there is a potential for a memory leak inside the Java VM here.
:Even with mayStillDoExpeccoCalls(true), only functions which are not depending on the step's activity may be called after the activity has finished. This includes event, logging and transcript/stderr functions, but no pin access or verdict reporting functions.
 

==== Pin Functions (Groovy) ====
Currently, Groovy blocks do not support a variable number of input or output pins.

Attention:
 Groovy uses many more reserved keywords for syntax than JavaScript or Smalltalk. These keywords cannot be used as pin names, and you will get a syntax error ("<foo> token not expected") if you try. Be careful to not name your pins as any of: "in", "return", "class", "private", "public", etc. As a proven best practice, add a "Pin" suffix to your pin names (i.e. name it "inPin", instead of "in").

===== Input Pins (Groovy) =====

*'''hasValue''' () Returns true if the pin has received a value

*'''value''' () Returns the value of the pin. Raises an error if the pin did not receive any value.

*'''valueIfAbsent''' (''alternativeValue'') Returns the value of a pin or the alternativeValue if the pin did not receive any value.
 

===== Output Pins (Groovy) =====

*'''isBuffered''' () True if the pin is buffered


*'''value''' (''data'') Writes the value.
 

==== Transcript, Stderr and Stdout (Groovy) ====

The expecco "<code>Transcript</code>", "<code>Stderr</code>" and "<code>Stdout</code>" are also accessible from Groovy code. However, only a limited subset of messages is supported:

*'''cr''' () Adds a linebreak (i.e. followup text will be shown on the next line)

*'''show''' (''arg'') Adds a textual representation of the argument, which can be a string, number or any other object.

*'''showCR''' (''arg'') A combination of show(), followed by a linebreak.

*'''writeLine''' (''string'') For compatibility with Java's PrintStream protocol.

*'''print''' (''string'') For compatibility with Java's PrintStream protocol (expecco 2.8).

*'''println''' (''string'') For compatibility with Java's PrintStream protocol (expecco 2.8).

*'''println''' () For compatibility with Java's PrintStream protocol (expecco 2.8).

In addition, stdout and stderr are also forwarded to the expecco Transcript window, depending on the settings in expecco ("''Extras''" → "''Settings''" → "''Execution''" → "''Tracing''" → "''Show Stdout and Stderr on Transcript''").
 

== Node.js (Bridged) Elementary Blocks ==

Node.js is an open source interpreter for JavaScript. For details on the language and libraries, visit [https://www.w3schools.com/nodejs "NodeJS Tutorial"] .
 You have to download and install "node" separately - the interpreter is not part of the expecco installation procedure (see [[Installing_additional_Frameworks/en | "Installing additional Frameworks"]]) and [https://nodejs.org/en/download/ https://nodejs.org/en/download] ).

Node.js code execution in expecco is supported via 2 different mechanisms:
* Node.js Bridged Action Blocks - these look at the outside like regular action blocks with typed input and output pins, which are available inside the action's code via "<code>.value()</code>" APIs. The bridge-partner in which the code is to be executed is started once and will remain an active process until terminated. Any state (data) created inside the bridge remains alive while the partner is running and the connection is alive.
* [[ElementaryBlock_Element/en#Node.js-Script_Blocks | Node.js-Script Action Blocks]] - these look like shell-script blocks, in that the standard input and output is used to interact with the script. For every individual script action, the script interpreter is started anew. No state is alive between and across actions (the script-interpreter is terminated after each action)

The following describes the first kind of blocks (bridged). Node.js-Script blocks are described elsewhere, in the [[ElementaryBlock_Element/en#Node.js-Script_Blocks | Node.js-Script Blocks]] chapter.

Code written as a Node.js elementary block is not executed directly by expecco. Instead, the code is forwarded to a node interpreter. This may be a local node process, whose sole purpose is to provide additional utility functions or which provides an interface to the actual system under test (SUT), or it may be on a remote system.

=== NodeJS Datatype Limitations ===
Because expecco objects and Node objects live in different processes,
no direct object access is possible between the two partners.
When objects are passed via an input pin from expecco to Node, or via an output pin from Node to expecco, the object is either converted to JSON on the sender side and reconstructed on the receiver side, or it is passed by reference, in that the sender transmits a "handle" (which is some unique number) to the partner.

Since the class system / object model is different, not all objects are exactly representable on the other side, and some information may be lost. If required, additional information must be explicitly passed (eg. by generating a string representation ''manually'').

==== Limited NodeJS Object Conversion ====
Some limited form of object conversion is automatically performed when passing expecco's Smalltalk objects to NodeJS, and back when returning values from NodeJS. This conversion especially affects values passed to/from pins of a NodeJS action.

The following table summarizes the conversion process:
{| Border
! from Smalltalk
! to NodeJS and from NodeJS
! to Smalltalk
!
|-
| String
| String
| String
|-
| Float (node ONLY supports IEEE double numbers)
| Float
| Float
|-
| Float, Double
| Float
| Float (Smalltalk Floats have double precision)
|-
| Fraction
| Float
| Float (Smalltalk Floats have double precision)
|-
| Boolean
| Boolean
| Boolean
|-
| Array of any above
| Array of any above
| Array of any above
|-
| -
| any
| any NodeJS object as Reference via "<code>makeRef(obj)</code>" fetch in Node via "<code>inpin.refValue()</code>"
|-
| Filename
| String (i.e. pathname)
| String
|-
| arbitrary Smalltalk Object (!)
| Object with slots
| Dictionary with slots
|}

(-) does not work. In general, only objects which can be represented by JSON can be transmitted between expecco and the node action.

==== No Smalltalk Classes, No Smalltalk Objects in NodeJS ====
Of course, no Smalltalk class can be used directly in NodeJS code.
And only a subset of Smalltalk objects (those which can be represented as JSON string) can be passed to/from NodeJS as described above.
However, all node.js code (packages/modules) are at your hands now!

In general: if more complex objects need to be interchanged, this must be either done by converting them to an array (of objects), possibly an array of arrays.
Or, alternatively to some ASCII representation (XML or JSON, for a more lightweight approach) and convert this back and forth.

It is also possible to pass Node-object-references from the Node interpreter to expecco, and pass it back to the Node interpreter later (usually in another action).
This is used to get connection, protocol or device handles from Node, and pass them to other (transmission or control) actions later.

==== Limited Error Reporting ====
Notice, that arithmetic errors are usually not reported by Node.
Dividing by zero or taking the logarithm of a negative number will deliver a Nan ("Not a Number") instead of raising an error. Thus you have to explicitly check the result from such computations in your code (this is different in expecco's builtin JavaScript actions, where an error is reported).

=== Debugging NodeJS Actions ===
Some debugging facilities are provided to support development of Node code.
If your code contains an endless loop, you can interrupt the Node interpreter
(via the "''Interrupt Execution''" button at the top right)
and get a debugger window, showing the call stack and local variables.

However, there are situations, when the Node interpreter gets completely locked up and ceases to react.
In this situation, you will have to shut down the Node interpreter via the "''Plugins''" → "''Bridges''" → "''Node JS''" → "''Close Connections''" menu function.
Of course, this also implies, that any state inside the Node interpreter is lost, and you'll have to rerun your test setup from the start.

===== Debugger Functions =====
Currently, you cannot look "into" objects, and you cannot modify the local variables.
The debugger looks very similar to the Smalltalk/JavaScript debugger
and supports ''continue'', ''line stepping'', ''stepping into called functions'', ''stepping out of called functions'',
''aborting an activity'' and ''terminating'' the whole node-interpreter.

===== Limitations of the Debugger =====
One problem which is encountered with the current node version is that the breakpoint line numbers
are sometimes off-by-one; this means, that the line reported by the node-debugger is wrong and
therefore also shown wrong in the debugger. This is a problem of the particular node version,
and may or may not appear in your concrete installation (i.e. node interpreter version).

Sorry, but we cannot currently provide a workaround for this problem, as we have not yet figured out,
what constellation of source-code/statement/situation leads to this problem.
(this problem was also reported by other node users in the internet forums).

=== NodeJS Code API ===

NodeJS code supports a '''subset''' of the above activity functions, which is intended provide an interface similar to the JavaScript and Smalltalk elementary code API. Of course, technically for every API function below, the code executing in the remote Node interpreter has to make a remote procedure call back to expecco. On the Node side, this is done very similar to the above described remote message mechanism, when messages are sent from expecco to a bridge.
Also notice, that due to the single threaded nature of Node programs, all functions which ask for a value from expecco (eg. "<code>environmentAt</code>") will take a callback argument, which is called when the return value arrives.

Be remonded that the objects described below are proxy objects inside node, which will forward messages back to expecco when functions listed below are called on them. Due to the roundtrip times, these will be relatively slow (in the order of milliseconds).

==== Variables seen by the Executed Node Function ====

The following variables are in the scope of the executed function:

*<code>Transcript</code> supports a few functions to display messages in the expecco Transcript window (see below)
*<code> Stdout </code> supports a few functions to display messages on expecco's stdout stream (see below)
*<code> Stderr </code> supports a few functions to display messages on expecco's stderr stream (see below)
*<code> Logger </code> supports <code>info()/warn()/error()/fatal()</code>; these are forwarded to the Smalltalk Logger object (see Logger)

*<code>__bridge__</code> the bridge object which handles the communication with expecco. The instance slot named "<code>asynchronous</code>" is of special interest if the called function uses asynchronous callbacks (see below)

==== Reporting (NodeJS) ====

*'''error''' (''infoString'',...) Report a defect (in the test). Stops execution. If the infoString argument contains "%i" placeholders ("%1","%2",...), these will be expanded by the remaining arguments. (eg. <code>logFail("foo:%1 bar:%2", 123, 234.0)</code> will generate the failure string "foo:123 bar:234.0").

*'''fail''' (''infoString'',...) Report a failure (in the SUT). Stops execution.

*'''inconclusive''' (''infoString'',...) Report an inconclusive test. Stops execution.

*'''activitySuccess''' (''infoString'',...) Finishes the current activity with success (same as "success()").

*'''success''' (''infoString'',...) Finishes the current activity with success (same as "activitySuccess()"). Please use "activitySuccess" ("success" is not supported in all bridges due to name conflictswith other libraries. For readability, it is better to use the same name in all bridges: "activitySuccess", which is supported on all bridges)

*'''pass''' (''infoString'',...) Finishes the current testCase with success.

*'''testPass''' (''infoString'',...) Same as pass(); for compatibility with bridged languages where "pass" is a reserved keyword (i.e. python).

==== Logging (NodeJS) ====

*'''logFail''' (''messageString''...) Adds a fail message to the activity log. Execution continues, but the test will be marked as failed. If the messageString argument contains "%i" placeholders ("%1","%2",...), these will be expanded by the remaining arguments. (eg. <code>logFail("foo:%1 bar:%2", 123, 234.0)</code> will generate the failure string "foo:123 bar:234.0").

*'''logError''' (''messageString''...) Adds a error message to the activity log. Execution continues, but the test will be marked as erroneous.

*'''logWarning''' (''messageString''...) Adds a warning to the activity log. Execution continues.

*'''logInfo''' (''messageString''...) Adds an info message to the activity log. Execution continues

*'''alert''' (''messageString'') Adds a warning message to the activity log, and also shows a DialogBox, which has to be confirmed by the operator. The dialog box and confirmation can be disabled by a settings flag in "''Extras''" → "''Settings''" → "''Execution''" → "''Log -Settings''" (by default it is enabled). Notice that the code in the bridge is suspended until the box is confirmed.

*'''warn''' (''messageString''...) Same as ''alert()'' (for Smalltalk protocol compatibility).

==== Reflection, Information, Queries and Accessing (NodeJS) ====

*'''nameOfAction''' () The name of the activity

==== Interaction with Expecco (NodeJS) ====

*'''call'''(<actionName>, <arg1>, <arg2>, ... <argN>, function(rslt...) {...}); Executes any other expecco action (inside expecco - not inside the node interpreter), and finally calls the callBack function, when the action has finished. Notice that this is an asynchronous callback; you should not perform any further actions after the call, but instead continue inside the callback (and signal final completion via "<code>activitySuccess() / error()</code>" call from there). The callback may expect multiple rslt-arguments, to get the output values of more than one pin. However, it is currently not possible to get the values of pins which are written multiple times (i.e. an error will be reported, if that is the case) See example below.

==== Event Sending (NodeJS) ====
* '''pushEvent''' (''payloadData'') pushes an event onto the global event handler's event queue. The payload is packed into an Event object with eventType "#default. Raises an error, if no global event handler process is running.

* '''pushEventType_data''' (''eventTypeSymbolOrNil'', ''payloadData'') pushes an event of type (or #default) onto the global event handler's event queue. Raises an error, if no global event handler process is running.

==== Environment Access (NodeJS) ====

*'''environmentAt'''(''varName'', function(err, rslt) {...}); Fetches a value from the expecco environment which is in scope of the current activity, and finally calls the callBack function, when the value has been retrieved (passing the retrieved value as argument). Notice that this is an asynchronous callback; you should not perform any further actions after the call, but instead continue inside the callback (and signal final completion via "<code>activitySuccess() / error()</code>" call from there). You can only read simple objects (numbers, booleans and strings) from node actions.

*'''environmentAtPut'''(''varName'', ''newValue'', function(err) {...}); Writes a value into the expecco environment which is in scope of the current activity, and finally calls the callBack function, when the value has been stored. Notice that this is an asynchronous callback; you should not perform any further actions after the call, but instead continue inside the callback (and signal final completion via "<code>activitySuccess() / error()</code>" call from there). The ''varName'' argument must be a string and ''newValue'' a simple object (number, boolean or string) from node actions.

==== Special Functions (NodeJS) ====
*'''makeRef''' (<anyNodeObject> [, <optionalName> ]) Generates a reference to a NodeJS object, which can be passed to expecco as an output pin value. Such reference objects can be passed back to NodeJS later and are dereferenced there back to the original object. This is used to pass NodeJS handles (i.e. server/client handles) to expecco and later back to NodeJS. Read below about reference passing vs. value passing. Notice that the nodeObject will be registered (i.e. remembered) inside the node interpreter, in order to be found later, when the reference is passed as input by another node action. When the reference is no longer needed, it should be deregistered by calling the "<code>releaseRef</code> function described below. Also notice, that expecco will do this automatically, when the reference object is finalized. See example below.

*'''releaseRef''' (<nodeObjectReference>) removes the reference from the registery inside the node interpreter. See example below.

*'''wait''' () Tells expecco to wait until one of the "<code>activitySuccess/error/fail/inconclusive</code>" functions is called. Use this if the action's execution is not finished when the execute() function returns, but instead will explicitly notify the finish from within a callback. This is also to be used if a pin value has to be written later by a callback function. See example and description of callbacks/async functions below.
*'''waitForPin''' (''pinName'') Tells expecco to wait until the given output pin receives a value. This is needed for async/await (promise resolved) pin values. See example and description of callbacks/async functions below.


==== Pin Functions (NodeJS) ====

Attention:
 Javascript uses many more reserved keywords for syntax than Smalltalk. These keywords cannot be used as pin names, and you will get a syntax error ("<foo> token not expected") if you try. Be careful to not name your pins as any of: "<code>in</code>", "<code>return</code>", "<code>class</code>", "<code>private</code>", "<code>public</code>", etc. As a proven best practice, add a "''Pin''" suffix to your pin names (i.e. name it "''inPin''", instead of "''in''").

===== Input Pins (NodeJS) =====

Currently, NodeJS blocks do not support a variable number of input or output pins.

*''pinName''.'''hasValue''' () Returns true if the pin has received a value

*''pinName''.'''isConnected''' () Returns true if the pin is connected

*''pinName''.'''value''' () Returns the value at the pin (the datum). Raises an error if the pin did not receive any value.

*''pinName''.'''refValue''' () Returns the object referenced by the value at the pin. The pin must have received a reference. Raises an error if the pin did not receive any value. Use this to pass back the original reference object to expecco. The input pin must have received a reference to a Node object as generated previously by "<code>makeRef</code>". Read below about reference passing vs. value passing.

*''pinName''.'''valueIfPresent''' () Returns the pin's datum if it has one, null otherwise. Similar to "<code>value()</code>", but avoids the exception.
*''pinName''.'''valueIfAbsent''' (''repl'') Returns the pin's datum if it has one, ''repl'' otherwise. Similar to "<code>value()</code>", but avoids the exception.

===== Output Pins (NodeJS) =====

Currently, NodeJS blocks do not support a variable number of input or output pins.


*''pinName''.'''isConnected'''() Returns true if the pin is connected (this can be used to prevent writing output values and thus speed up the execution, especially if big arrays of data values are generated)

*''pinName''.'''value''' (''data'') Writes the value.

==== Transcript, Stderr and Stdout (NodeJS) ====

The expecco "<code>Transcript</code>", "<code>Stderr</code>" and "<code>Stdout</code>" are also accessible from Node code. However, only a limited subset of messages is supported:

*'''cr''' () Adds a linebreak (i.e. followup text will be shown on the next line)

*'''show''' (''arg'') Adds a textual representation of the argument, which can be a string, number or any other object.

*'''show''' (''fmt'', ''arg''...) Like "<code>show()</code>, but "%i" sequences in the format argument are expanded by the corresponding arg strings.

*'''showCR''' (''arg'') A combination of show(), followed by a linebreak.

*'''showCR''' (''fmt', ''arg''...) Like "<code>showCR()</code>, but "%i" sequences in the format argument are expanded by the corresponding arg strings.

In addition, stdout (console.log) and stderr (console.error) are also forwarded to the expecco Transcript window, depending on the settings in expecco ("''Extras''" → "''Settings''" → "''Execution''" → "''Tracing''" → "''Show Stdout and Stderr on Transcript''").
 

=== Reference passing vs. value passing of Node objects to expecco ===

When values are passed via an output pin from Node to expecco, two mechanisms are possible:
* pass by value The object's JSON string is generated and passed to expecco. There, the JSON encoding is decoded and a corresponding expecco object is constructed. Conceptional, the expecco object is a copy of the original object.

* pass by reference The object is remembered inside Node, and a reference is passed to expecco. Whenever this reference object is later sent to Node again (via an input pin), the original Node object is retrieved and passed to the JavaScript code. This mechanism preserves the object's identity on the Node side and must be used for object handles (such as protocol handles).

The default mechanism is "''pass by value''". To pass a reference, use "<code>makeRef(obj)</code>" and pass the generated reference to an output pin.
==== Example (NodeJS) ====
The following code snippet sends an object's reference to an output pin:

function execute() {
 ... generate a handle object ...
outputPin.value( makeRef (someHandle , "aNodeHandle" ) );
}

the returned handle can later be sent via an input pin to another Node action, and used transparently there:

function execute() {
var handle = inputPin.value();
... do something with handle ...
}

occasionally, it is required that a reference which was received via an input pin must later be sent to an output pin again, preserving the original reference. This is to prevent additional memory allocations which would result from calling "<code>makeRef</code>" again (you would get multiple references to the same object).
For this, use "<code>inputPin.refValue()</code>" and send this to an output pin without a "<code>makeRef</code>":

function execute() {
var handle = inputPin.value();

... do something with handle ...
// send the original reference to the output
outputPin.value( inputPin.refValue() );
}

Finally, you want to release the reference inside the node interpreter, to prevent memory leaks.
Usually, this should be called, when a handle becomes invalid (e.g. when a connection handle is closed).

For this, call the "<code>releaseRef</code>" function (on the node side), passing the reference instead of the referenced object.
 For example, a close-connection action block might look like:

function execute() {
var reference = inputPin.refValue();
var referredObject = inputPin.value();

... do something with referredObject ...
closeConnection( referredObject );
// release to prevent memory leaks
releaseRef(referredObject);
}

=== Asynchronous and Callback Functions ===
A common pattern in node is "''continuation passing style''" control flow. That means, that many functions expect a function as callback argument, which is called later whenever the requested operation has finished. This is used especially with I/O and protocol related operations (such as socket connect, http requests, client connect setup etc.).
A similar situation arises with async functions, which somehow get a promise as value, and the promise is resolved via an await.

If your "<code>execute</code>" function calls any of those or is an async function which awaits on a promise, it has to tell expecco that the node-action is effectively still active when the execute function returns and that expecco should wait for an explicit finished-notification. This is done by either calling either "<code>wait()</code>" or "<code>waitForPin()</code>" somewhere within the execute function.

Then expecco will continue to wait for the action to be finished until the node code calls one of the "<code>fail()</code>", "<code>error()</code>", "<code>success()</code>", "<code>pass()</code>", "<code>inconclusive()</code>" functions (listed above) or - in case of a previous <code>waitForPin()</code>, until that pin receives a value.

Example 1: the following code fragment represents a typical callback situation: the "myProtocolConnect()" call gets a callback, which will be called later (asynchronously), when a connection is established. However, "myProtocolConnect()" will return immediately. Without the "wait()" at the end, expecco would assume that the action has finished and would proceed with other actions (possibly without any output being written to the output pin (actually, it would later detect a value being written by an already finished action, and write a warning message to the console and the log).

function execute() {
 ... call a function which does a callback ...
myProtocolConnect( ... , function(err) {
... callback possibly called much later ...
// tell expecco that we're done
if (err) {
error("some error happened: "+err.toString());
} else {
outputPin.value(someConnectionHandle);
success();
}
});
// tell expecco to continue waiting
wait();
}

Notice that callbacks can be either written as functions (with a statement body):
function(err) { statement; ... statement; }
or as a lambda expression, where the body is an expression:
(err) => expression

Example 2: the following code fragment is typical for async/await functions. Similar to the above, but covered by syntactic sugar which makes this less obvious, the execute function will return early, but execute code asynchronously due to the awaited promise:

async function execute() {
let appiumMacDriver = require("appium-mac-driver");

// due to the async operations,
// this execute function will effectively finish when
// the await receives the value,
// and it is written to the pin.
// tell expecco that the function is finished when that pin
// receives a value
waitForPin(sessionOut);

let driver = new appiumMacDriver.MacDriver();
let session = driver.createSession(defaultCaps);
let s = await session;
sessionOut.value(s);
}

Example 3: The following example demonstrates what happens if the "wait()" call is missing. The code below installs a callback which writes to an output pin 1 second AFTER the finished action:

function execute() {
output.value("Value1");
setTimeout(function(err) {
output.value("Value2");
}, 1000);
}

the above code will lead to an error.

The correct version is:

function execute() {
output.value("Value1");
setTimeout(function(err) {
output.value("Value2");
success();
}, 1000);
wait();
}

Up to version 23.2, this situation was not always detected and could have lead to an output value being written to a same-named output pin of a followup action (iff another bridged action was triggered which was of the same type, that second action's output was sometimes written, depending on timing constraints). With version 24.1, this is detected and an error message is sent to the Transcript (it cannot be reported as an error in the activity log, because the first action which is responsible has already finished, whereas the second action (which is innocent) cannot be blamed for that).

=== Calling other Expecco Actions ===
Any expecco action (i.e. elementary or compound) can be called from Node code.
However, as node uses a callback mechanism, the code looks a bit different from other languages, in that an additional callback argument is to be passed. You can pass either the name or the UUID of the activity which is to be called.
Arguments are passed to the called action's input pin (top to bottom).

For now, there is a limitation, in that only a single value (per pin) can be passed to the callback (i.e. you cannot get the values of pins which are written multiple times).
 Example:

function execute() {
 ... call an expecco activity ...
call("myAction", 100, 200 ,
function(result) {
... callback gets the first value from myAction's first output pin ...
success();
});
// not reached
}

Notice, that in order to get a sequence of calls, the code needs nested functions, as in:

function execute() {

call("myAction1", 1000, 2000,
function(rslt1) {
Transcript.showCR("after first call: "+rslt1);
call("myAction2", 10000, 20000,
function(err, rslt2) {
Transcript.showCR("after second call: "+rslt2);
success();
});
// not reached
});
// not reached
}

If the called action has multiple output pins, provide a callback function which expects more than one rslt argument,
as in:
function execute() {

call("actionWithTwoOutputPins", 1000, 2000,
function(valueAtPin1, valueAtPin2) {
Transcript.showCR("received two values: "+valueAtPin1+" and: "+valueAtPin2);
success();
});
// not reached
}

=== Reading expecco Environment Variables ===
Expecco variables can be fetched via the "<code>environmentAt</code>" function. Notice, that this takes a second callback function as argument, which is called when the value is (later) received. The execution of the action proceeds with this continuation, and "<code>environmentAt</code>" does not return.

 For example:
function execute() {
environmentAt("variable1", function(err, varValue) {
Transcript.showCR("the variable value is: "+varValue);
success();
});
// not reached
}

=== Executing Node Actions in Multiple Node Interpreters ===
In order to test the interaction between multiple node programs,
or to generate load for performance tests,
it may be required to start multiple node interpreters,
and run action code in them.

This chapter describes how to start a node interpreter and how to interact with them.

==== Starting another Node Interpreter on the Local Machine ====

Every Node bridge uses the given port for bridge communication plus the next port for debugging.
Every bridge running on the same host must use different ports.
The default bridge uses port 8777 (and 8778 for debugging).
Thus, additional bridges should be given ports incremented in steps of 2,
and useful ports are 8779, 8781, 8783 etc. for additional node bridges.

===== Programmatic Start =====

nodeBridge := Expecco
newNodeJSBridgeConnectionForHost:hostName port:portNr
in:aDirectoryOrNil.

===== Using an Action from the Standard Library =====
use the "''Start new Local Node Bridge''" action from the library.

===== Executing an Action inside another Node Interpreter =====

Either add a "''nodejs''" input pin to the action (passing the other node-bridge's handle) or
set the "<code>NODEJS</code>" environment variable before the action.
An example is found in the "<code>d62_Event_Queue_Demos.ets</code>" suite: 
[[Datei:Event_Queue_Demo.png|600px|]]

=== Node Packages ===

===Example: Installing Additional Node Packages ===
Use the Node package manager "<code>npm</code>" to install packages.
 The "''Extras''" → "''Bridges''" → "''Node Bridge''" menu also contains an entry to install npm packages.
 Find packages in [https://www.npmjs.com https://www.npmjs.com].

For example, assume you need the current city weather in a suite, navigate to "https://www.npmjs.com", search for "weather", find the "<code>city-weather</code>" package and click on it. You will arrive on a page giving installation instructions and sample code at the end.
Scroll down to the example code and keep that page open (we can use the code later).

Open a cmd/shell window and execute on the command line:
npm install city-weather

=== Examples: Using a Node Package in Expecco ===
==== Example1: Access to the City Weather Service ====
For a first test, we will take the original code from the example.
Create a new node action, and enter the code:
var weather = require("city-weather");

function execute() {
weather.getActualTemp('Rome', function(temp){
console.log("Actual temperature: " + temp);
});
}

(you can copy-paste the sample code from the webpage)

Open the expecco console (aka "Transcript" via the "''Extras''" → "''Tools''" → "''Transcript''" menu item) and run the test.
A temperature should be displayed on the Transcript.

Now add an input pin named "''city''", and change the code to:
...
weather.getActualTemp(city.value(), function(temp){
...
and try the code in the "''Test/Demo''" page with a few different cities at the input pin.

Then, add an output pin named "''temperature''", and change the code again to:
var weather = require("city-weather");

function execute() {
weather.getActualTemp(city.value(), function(temp){
console.log("Actual temperature: " + temp);
temperature.value( temp );
});
}

if you now execute this action, you will notice, that the output pin does NOT get the value.
The reason is, that the pin is written by a node-callback function, which is called at a time after the action's "<code>execute</code>" function has already finished.
Thus, we have to tell expecco, that it should wait until the callback is actually called.
For this, you should add a call to the "<code>wait()</code>" function.

This tells expecco, that the execute-function is not complete, and will wait for one of the "<code>success/fail/error</code>" functions to be called.
So we also have to add a call to "<code>success()</code>" inside the callback (otherwise, expecco would wait forever).

Thus, we change the code to:
var weather = require("city-weather");

function execute() {
weather.getActualTemp(city.value(), function(temp){
console.log("Actual temperature: " + temp);
temperature.value( temp );
success();
});
wait();
}

As a final step, you should remove or comment the call to "<code>console.log()</code>" and add some error reporting, in case a city was not found:
var weather = require("city-weather");

function execute() {
weather.getActualTemp(city.value(), function(temp){
// console.log("Actual temperature: " + temp);
if (temp == "City was not found") {
error(temp+": "+city.value());
}
temperature.value( temp );
success();
});
wait();
}

==== Example2: Access OpenStreetMap Services ====
This is described in a [[Node_Examples/en | separate document]].

== Bridged Python Elementary Blocks ==

Code written as a Python elementary block is not executed directly by expecco. Instead, the code is forwarded to a python interpreter. This may be a local python process, whose sole purpose is to provide additional utility functions or which provides an interface to the actual system under test (SUT), or it may be on a remote system.

==== Python Versions ====
Python is available in 2 major dialects (2.x vs. 3.x) and different implementations (cPython, Jython, IronPython):
* use '''jython''', if you have to interface/embed java classes or jars;
* use '''ironPython''', if you have to interface with .NET assemblies;
* use '''python3''' to interface to modern frameworks such as Tesseract (optical character recognition), computer vision, Tensorflow (machine learning) etc.
* use '''python2''' for some older frameworks, which have not yet been ported to the newer python3 (notice, that support for python2 is going to cease soon)

Of course, if you need to interface to a Python module which is specifically written for a version, that specific version is obligatory.

You have to download and install Python, Python3, Jython and/or IronPython separately; these interpreters are not part of the expecco installation procedure.
 See ([[Installing_additional_Frameworks/en | "Installing Additional Frameworks"]]) and download Python from [https://www.python.org/downloads https://www.python.org/downloads],
[https://jython.org/downloads.html http://jython.org/downloads.html] for Jython, and [ https://ironpython.net/download/] for IronPython.

Additional frameworks may be needed as prerequisite (i.e. Java for Jython, Mono for IronPython on non-Windows machines).

==== Bridged vs. Scripted Actions====
Similar to Node, Python code execution is supported via 2 different mechanisms:
* '''Bridged Python''' action blocks - these look at the outside like regular action blocks with typed input and output pins, which are available inside the action's code via "<code>.value()</code>" APIs. Objects can be interchanged between expecco and the python process either by value or by reference. The bridge-partner in which the code is to be executed is started once and will remain an active process until terminated. Any state (data) created inside the bridge remains alive while the partner is running and the connection is alive.
* '''Python-Script''' action blocks - these look like shell-script blocks, in that the standard input and output is used to interact with the script. For every individual script action, the interpreter (i.e. Python) is started anew. No state is alive between and across actions (the python-interpreter is terminated after each action), and no objects can be exchanged (except for very simple objects by means of reading encoded objects via stdin/stdout/stderr).

The following describes the first kind of blocks (bridged). Script blocks are described elsewhere, in the [[ElementaryBlock_Element/en#Python_Script_Blocks | Python-Script Blocks]] chapter.

=== Debugging Python Actions ===
Debug support for Python actions is still being developped and more features are added with newer versions. However, there are probably better IDEs available and it might be a good idea to develop and debug Python code in your preferred IDE, and only add interface code to already debugged modules as expecco actions (this is certainly a matter of your personal preferences; in the past, interfaces to many modules have been implemented using only expecco's debug facilities).

In order to support debugging of Python actions, you have to install either the "''debugpy''" or the "''ptvsd''" package (*) with:
pip install debugpy
or:
pip3 install debugpy
or:
python3 -m pip install debugpy

*) ptvsd is no longer maintained and has been replaced by the debugpy package. Ptvsd might be obsolete by the time of reading this.

For more information on the ptvsd package, see [https://pypi.org/project/ptvsd https://pypi.org/project/ptvsd] and [https://github.com/Microsoft/ptvsd https://github.com/Microsoft/ptvsd].
 For debugpy, refer to [https://pypi.org/project/debugpy https://pypi.org/project/debugpy].

Notice that the debug features are currently not supported by python2 or jython.

=== Python Datatype Limitations ===

==== Limited Python Object Conversion ====
Some limited form of object conversion is automatically performed when passing expecco objects to Python, and back when returning values from Python. This conversion especially affects values passed to/from pins of a Python action.

The following table summarizes the conversion process:
{| Border
! from Expecco (Smalltalk)
! to Python and from Python
! to Expecco
!
|-
| String
| String
| String
|-
| Float 
| Float
| Float
|-
| Float, Double
| Float
| Float (Smalltalk Floats have double precision)
|-
| Fraction
| Float
| Float (Smalltalk Floats have double precision)
|-
| Boolean
| Boolean
| Boolean
|-
| Array of any above
| Array of any above
| Array of any above
|-
| ByteArray
| Array
| Array
|-
| -
| any
| any Python object as Reference via "<code>makeRef(obj)</code>"
|-
| Python object reference as previously generated by "<code>makeRef(obj)</code>" fetch the reference in Python via "<code>inpin.refValue()</code>" or the value via "<code>inpin.value()</code>"
| fetch the reference in Python via "<code>inpin.refValue()</code>" or the value via "<code>inpin.value()</code>"
| send value or reference with "<code>makeRef(obj)</code>"
|-
| Filename
| String (i.e. pathname)
| String
|-
| arbitrary Smalltalk Object (!)
| Object with slots
| Dictionary with slots
|}

(-) does not work. In general, only objects which can be represented by JSON can be transmitted between expecco and the python action.

==== No Smalltalk Classes, No Smalltalk Objects in Python ====
Of course, no Smalltalk class can be used directly in Python code.
And only a subset of Smalltalk objects (those which can be represented as JSON string) can be passed to/from Python as described above.

In general: if more complex objects need to be interchanged, this must be either done by converting them to an array (of objects), an array of arrays or a dictionary.
Or, alternatively to some ASCII representation (XML or JSON, for a more lightweight approach) and convert this back and forth.

It is also possible to pass an object-reference from the Python interpreter to expecco, and pass it back to the Python interpreter later (usually in another action).
This is used to get connection, protocol or device handles from Python, and pass them to other (transmission or control) actions later.


==== Limited Syntax Highlighting, Code Completion and Debugging Support ====
Currently, all of those are very limited: the syntax highlighter only detects keywords and some constants as such; code completion does not work and no interactive debugger is provided currently.

=== Bridged Python Code API ===

WARNING: Bridged Python Elementary Actions are still being developed - their behavior might be subject to changes (aka the protocol will be extended).

Python code may consist of function- and/or class definitions. Among the functions, there should be one named "<CODE>execute()</CODE>"; typically, that is the last defined function, which calls into other python code. If no "execute"-function is defined, expecco tries to call "<code>main()</CODE>" as fallback. This special behavior was added to make it easier to reuse existing script code.

Bridged Python code can use activity functions similar to the above Groovy or Node actions.
The API is intended to provide an interface similar to the JavaScript and Smalltalk elementary code API. Of course, technically for every API function below, the code executing in the remote Python interpreter has to make a remote procedure call back to expecco. On the Python side, this is done very similar to the above described remote message mechanism, when messages are sent from Smalltalk to a bridge.

==== Variables seen by the Executed Python Function ====

The following variables are in the scope of the executed function:

*<code>Transcript</code> supports a few functions to display messages in the expecco Transcript window (see below)
*<code> Stdout </code> supports a few functions to display messages on expecco's stdout stream (see below)
*<code> Stderr </code> supports a few functions to display messages on expecco's stderr stream (see below)
*<code> Logger </code> supports <code>info(), warn(), error() and fatal()</code>; these are forwarded to the Smalltalk Logger object (see below)
*<code> Dialog </code> supports <code>confirm(), warn(), information()</code>; these are forwarded to the Smalltalk Dialog object (see below)


==== Reporting (Python) ====

*'''error''' (''infoString'') Report a defect (in the test). Finishes the current activity with an ''error'' verdict.

*'''fail''' (''infoString'') Report a failure (in the SUT). Finishes the current activity.

*'''inconclusive''' (''infoString'') Report an inconclusive test. Finishes the current activity.

*'''activitySuccess''' (''infoString'') Finishes the current activity with success (same as "success()").

*'''testPass''' (''infoString'') Finishes the current testCase with success. This has the same effect as "pass()" in other actions - its name had to be changed because "pass" is a reserved keyword in Python.

==== Logging (Python) ====

*'''logFail''' (''messageString'') Adds a fail message to the activity log.

*'''logError''' (''messageString'') Adds a error message to the activity log.

*'''logWarning''' (''messageString'') Adds a warning to the activity log.

*'''logInfo''' (''messageString'') Adds an info message to the activity log.

*'''alert''' (''messageString'') Adds a warning message to the activity log, and also shows a DialogBox, which has to be confirmed by the operator. The dialog box and confirmation can be disabled by a settings flag in the "''Execution''" - "''Log -Settings''" dialog (by default it is disabled).

*'''warn''' (''messageString'') Same as ''alert()'' (for Smalltalk protocol compatibility).

==== Reflection, Information, Queries and Accessing (Python) ====



==== Interaction with Expecco (Python) ====
*'''call'''(<actionName>, <arg1>, <arg2>, ... <argN>); Executes any other expecco action (inside expecco - not inside the Python interpreter), and returns the generated output pin values as a tuple It is currently not possible to get the values of pins which are written multiple times (i.e. an error will be reported, if that is the case) See example below.

==== Environment Access (Python) ====
*'''environmentAt'''(<varName>); Fetches and returns a value from the expecco environment which is in scope of the current activity. You can only read simple objects (numbers, booleans and strings) from python actions.

*'''environmentAtPut'''(<varName>, <newValue>); Writes a value into the expecco environment which is in scope of the current activity. You can only write simple objects (numbers, booleans and strings) from python actions.


==== Event Sending (Python) ====
* '''pushEvent''' (''payloadData'') pushes an event onto the global event handler's event queue. The payload is packed into an Event object with eventType "<code>#default</code>. Raises an error, if no global event handler process is running.

* '''pushEventType_data''' (''eventTypeSymbolOrNil'', ''payloadData'') pushes an event of type (or <code>#default</code>) onto the global event handler's event queue. Raises an error, if no global event handler process is running.

==== Special Functions (Python) ====
*'''makeRef''' (<anyPythonObject>) Generates a reference to a Python object, which can be passed to expecco as an output pin value. Such reference objects can be passed back to Python later and are dereferenced there back to the original object. This is used to pass Python handles (i.e. server/client handles) to expecco and later back to Python. Read below about reference passing vs. value passing. Notice that the pythonObject will be registered (i.e. remembered) inside the python interpreter, in order to be found later, when the reference is passed as input by another node action. When the reference is no longer needed, it should be deregistered by calling the "<code>releaseRef</code> function described below. Also notice, that expecco will do this automatically, when the reference object is finalised. See example below.

*'''releaseRef''' (<nodeObjectReference>) removes the reference from the registery inside the Python interpreter. See example below.

*'''wait''' () Tells expecco to wait until one of the <code>success()</code>, <code>error()</code>, <code>fail()</code>, or <code>inconclusive()</code> functions is called. Use this if a pin value has to be written later by a callback function. See explanation of [[#Asynchronous_and_Callback_Functions|async callbacks]] and the example in the NodeJS API description.

*'''bridge_inMainThread''' (task) OS X only: Task must be a lambda expression which is executed by the main thread (as opposed to the bridge connection thread). This is required on eg. OS X to run code which interacts with OS X windowing framework. On non-OSX systems, this executes the task directly (and also in the main thread). Typical use: <code>bridge_inMainThread(lambda: someWindow.show() )</code>

==== Pin Functions (Python) ====
Currently, python blocks do not support a variable number of input or output pins.

Attention:
 Python uses many more reserved keywords for syntax than Smalltalk. These keywords cannot be used as pin names, and you will get a syntax error if you try. Be careful to not name your pins as any of: "<code>import</code>", "<code>return</code>", "<code>def</code>", "<code>if</code>" etc. As a proven best practice, add a "''Pin''" suffix to your pin names (i.e. name it "''inPin''", instead of "''in''").

===== Input Pins (Python) =====

*''pinName''.'''hasValue''' () Returns true if the pin has received a value

*''pinName''.'''isConnected''' () Returns true if the pin is connected

*''pinName''.'''value''' () Returns the value at the pin (the datum). Raises an error if the pin did not receive any value.

*''pinName''.'''refValue''' () Returns the object referenced by the value at the pin. The pin must have received a reference. Raises an error if the pin did not receive any value. Use this to pass back the original reference object to expecco. The input pin must have received a reference to a Python object as generated previously by "<code>makeRef</code>". Read below about reference passing vs. value passing.
*''pinName''.'''valueIfPresent''' () Returns the pin-datum if it has one, None otherwise. Similar to <code>value()</code>, but avoids the exception.
*''pinName''.'''valueIfAbsent''' (''repl'') Returns the pin's datum if it has one, ''repl'' otherwise. Similar to <code>value()</code>, but avoids the exception. Use this, if "None" is a possible value at the pin, and the code needs to distinguish between getting a "None" at the pin and not having a value at all at the pin.


===== Output Pins (Python) =====



*''pinName''.'''value''' (''data'') Writes the value.

==== Transcript, Stderr and Stdout (Python) ====

The expecco "<code>Transcript</code>", "<code>Stderr</code>" and "<code>Stdout</code>" are also accessible from Python code. However, only a limited subset of messages is supported:

*'''cr''' () Adds a linebreak (i.e. followup text will be shown on the next line)

*'''show''' (''arg'') Adds a textual representation of the argument, which can be a string, number or any other object.

*'''show''' (''fmt'', ''arg''...) Like "<code>show()</code>, but "%i" sequences in the format argument are expanded by the corresponding arg strings.

*'''showCR''' (''arg'') A combination of show(), followed by a linebreak.

*'''showCR''' (''fmt'', ''arg''...) Like "<code>showCR()</code>, but "%i" sequences in the format argument are expanded by the corresponding arg strings.

*Transcript '''clear''' () Clears the contents of the Transcript window (new in 24.2)

*Transcript '''raiseWindow''' () Makes the Transcript window visible (new in 24.2)

In addition, stdout (console.log) and stderr (console.error) are also forwarded to the expecco Transcript window, depending on the settings in expecco ("''Extras''" → "''Settings''" → "''Execution''" → "''Tracing''" → "''Show Stdout and Stderr on Transcript''").
 

==== Dialog (Python) ====
Some of expecco's Dialog messages are forwarded from Python:
*'''information''' (''msg'') (new in 23.2) Opens an information dialog. I.e. "<code>Dialog.information("Hello")</code> will show "Hello" in a popup dialog window.

*'''confirm''' (''msg'') Opens a Yes/No confirmation dialog (and returns True/False)

*'''request''' (''msg'') Opens a dialog asking for a string (and returns the entered string or None on cancel)

*'''requestPassword''' (''msg'') Opens a dialog asking for a password string (and returns the entered string or None on cancel)

*'''requestFilename''' (''msg'') (new in 23.2) Opens a dialog asking for a file name string (and returns the entered file name or None on cancel)

=== Global and Static Variables ===
Python actions are defined within the scope of another function, to prevent accidentically overwriting/redefining any global.
Thus, you have to access globals via "globals().get("name")".

==== Static Variables ====
Starting with v24.1, static variables (which are visible within one activity and which are preserved across calls) can be defined by
prepending the execute function's code with:
# start of static definitions
... any variables which should be static ...
# end of static definitions

Notice that these comment lines must be written exactly as above.
 As an example, the following uses a static variable to increment a counter whenever the action is Ivoked:
# start of static definitions
count=0
# end of static definitions

def execute():
nonlocal count

count = count + 1
print(f"count={count}")

Notice that the above example does not work in pre 24.1 versions.
 Also notice, that the static definitions are re-executed whenever the action code is changed or recompiled (i.e. that the count variable is reset to 0).

==== Global Variables ====

Example of a global variable that can also be used in other modules.

Caution: Please make sure that the name of the global variable is unique in your test suite!

def execute():
global count
try:
count
except NameError:
# Throws a NameError if not yet initialised
count = 0
count = count + 1
print(f"count={count}")

=== Printing Debug Messages in Python ===
Be aware, that the stdout stream is buffered in Python. Thus, debugprints generated by print might not appear immeditely.
 Eg, the following code:
print("start")
time.sleep(10)
print("end")
will show both lines after the sleep.

Use
sys.stdout.flush()
to force messages to be passed immediately to expecco; eg:
print("start")
sys.stdout.flush()
time.sleep(10)
print("end")

=== Python Asynchronous and Callback Functions ===
If output pins are to be written by a callback which is invoked AFTER the python function returned, the expecco activity will already be finished, and the pin will NOT be written.
Instead, a warning is generated in the log.

You MUST tell expecco that the execute function has not yet finished, by calling "wait()" and signal the real activity end in the callback via one of "success()", "error()"or "fail()".

For a detailed description of this mechanism, read the
[[#Asynchronous and Callback Functions|corresponding section]] in the Node API.

=== Reference passing vs. value passing of Python objects to expecco ===

When values are passed via an output pin from Python to expecco, two mechanisms are possible:
* pass by value The object's JSON string is generated and passed to expecco. There, the JSON encoding is decoded and a corresponding expecco object is constructed. Conceptional, the expecco object is a copy of the original object.

* pass by reference The object is remembered inside Python, and a reference is passed to expecco. Whenever this reference object is later sent to Python again (via an input pin), the original Python object is retrieved and passed to the Python code. This mechanism preserves the object's identity on the Python side and must be used for object handles (such as protocol handles).

The default mechanism is "''pass by value''".
 To pass a reference, use "<code>makeRef(obj)</code>" and pass the generated reference to an output pin.

When objects are passed from expecco to python, this is transparent. Python will automatically resolve passed in references. Thus you can send a "pointer" to an object to an output pin via "<code>makeRef(obj)</code>" and pass it to another Python action, where the value will refer to the original object.

==== Example (Python) ====
The following code snippet sends an object's reference to an output pin:

def execute():
 ... generate a handle object ...
outputPin.value( makeRef (someHandle ) )

the returned handle can later be sent via an input pin to another Python action inside the same bridge, and use transparently there:

def execute():
handle = inputPin.value()
... do something with handle ...
}

occasionally, it is required that a reference which was received via an input pin must later be sent to an output pin again, preserving the original reference. This is to prevent additional memory allocations which would result from calling "<code>makeRef</code>" again (you would get multiple references to the same object).
For this, use "<code>inputPin.refValue()</code>" and send this to an output pin without a "<code>makeRef</code>":

def execute():
handle = inputPin.value();

... do something with handle ...
# send the original reference to the output
outputPin.value( inputPin.refValue() )

Finally, you want to release the reference inside the Python interpreter, to prevent memory leaks.
Usually, this should be called, when a handle becomes invalid (e.g. when a connection handle is closed).

For this, call the "<code>releaseRef</code>" function (on the node side), passing the reference instead of the referenced object.
 For example, a close-connection action block might look like:

def execute():
reference = inputPin.refValue()
referredObject = inputPin.value()

... do something with referredObject ...
closeConnection( referredObject )
# release to prevent memory leaks
releaseRef(referredObject)



=== Calling other Expecco Actions (Python) ===
Not yet implemented

Any expecco action (i.e. elementary or compound) can be called from Python code.
You can pass either the name or the UUID of the activity which is to be called.
Arguments are passed to the called action's input pin (top to bottom).

For now, there is a limitation, in that only a single value (per pin) can be returned (i.e. you cannot get the values of pins which are written multiple times).
 Example:

def execute():
 ... call an expecco activity ...
result = call("myAction", 100, 200)

=== Python2 vs. Python3 ===
Although python2 is going to be obsoleted soon, there are still many packages and frameworks around, which require that version.

If all of your actions use the same python version, specify it in the "Python" field of the interpreter settings dialog.
Otherwise, change individual action's python version via the "Language" comboList, above the code editor (change to "BridgedPython2" or "BridgedPython3" to make it explicit).

Paths to the explicit versions and to the unspecific version are all defined in the pathon settings.

=== Reading expecco Environment Variables (Python) ===
Expecco variables can be fetched via the "<code>environmentAt</code>" function.
 For example:
def execute():
varValue = environmentAt("variable1")
...

=== Python Packages ===
You should install python packages using "pip" or "pip3", depending on the python version, for which a package is to be installed.
For more information, please consult the [http://pip.pypa.io pip documentation].

On Windows, "pipwin" seems to perform best, if additional C/C++ libraries need to be installed or compiled (eg. "pipwin install pyaudio").

When installing, make sure that the packages are installed in the correct target directory, as per Python environment; i.e. if you have multiple versions of the interpreter or virtual environments, make sure that the Python as started by expecco (and defined in the settings) uses and sees the correct module path.

===Installing Additional Python Packages ===
Use the Python package installer "<code>pip</code>" (or "<code>pip3</code>") to install packages.
The "''Plugins''" → "''Bridges''" → "''Python Bridge''" menu also contains an entry to install pip packages.
If you use virtual environments, make sure that your packages are installed in the correct location.

Find packages in [https://pypi.org/ https://pypi.org/] or [https://docs.python.org/3/py-modindex.html https://docs.python.org/3/py-modindex.html].



=== Accessing Assemblies in IronPython ===
Because IronPython executes inside a CLR environment, it has access to any assembly (written in any language).
For this, IronPython provides a special language extension, which is described in detail in [[https://ironpython.net/documentation/dotnet/dotnet.html the IronPython documentation]].

Example:
*** to be added **

=== Example 1: Using the "overpy" Python Package (open street map access) in Expecco ===
In this example, we will access the OpenStreetMap API to fetch information about a particular street
("Straße der Nationen") in a given city ("Chemnitz").

The example was taken from [https://pypi.org/project/overpy https://pypi.org/project/overpy] which is documented in [https://python-overpy.readthedocs.io/en/latest/index.html https://python-overpy.readthedocs.io/en/latest/index.html]. It requires python3 (you will get a UnicodeEncodeError if you try it in python2).

First, install the package with:
pip3 install overpy

For a first test, we will take the original code from the example.
Create a new Python action, and enter the code:
import overpy

api = overpy.Overpass()

def execute():
# fetch all ways and nodes
result = api.query("""
way(50.746,7.154, 50.748,7.157) ["highway"];
(._;>;);
out body;
""")

for way in result.ways:
print("Name:%s" % way.tags.get("name", "n/a"))
print(" Highway:%s" % way.tags.get("highway", "n/a"))
print(" Nodes:")
for node in way.nodes:
print(" Lat:%f, Lon:%f" % (node.lat, node.lon))

(you can copy-paste the sample code from the webpage)

Open the expecco console (aka "Transcript" via the "''Extras''" → "''Tools''" → "''Transcript''" menu item) and run the test.
A list of street nodes should be displayed on the Transcript.

=== Example 2: Accessing other Python Packages or Individual Script Files ===
The following works in 19.2 and later. 
In the following example, functions contained in a regular Python script file are called.
We assume, that the file is named "MyLib.py", and located in some directory ''DIR'':
 
DIR/MyLib.py:
def fun1(a,b):
return a+b;

def fun2(a,b):
return a-b;

We also assume, that you have created a new python action block, containing the code:

import MyLib

def execute():
Transcript.showCR("fun1:" + str(MyLib.fun1(10,20))
+ " fun2:" + str(MyLib.fun2(10,20)))

If you execute this action, you will probably get a "Module Not Found" error from python,
(unless DIR is already in your PYTHONPATH environment variable).

To fix the problem, open the "''Extras''" → "''Settings''" → "''External Script Interpreters''" → "''Python''" dialog,
and add DIR to the "Module Path" value. Notice that on Unix/Linux, you have to separate directories with colons ":", whereas under Windows, you'll have to separate them with semicolons ";".

You will have to shut down the already running Python interpreter and restart it, for the new PYTHONPATH setting to become valid. For this, use the "''Plugins''" → "''Bridges''" → "''Python Bridge''" → "''Shutdown Interpreters''" menu item (or shut down all external interpreters via the "''Extras''" → "''Debug''" menu).

=== Example 3: Accessing Python Script Files in Attachments ===
The following works in 19.2 and later. 
You can add Python script files (i.e. like the "MyLib.py" file in the above example) as attachment to to the suite. For this you have to add "$(Attachments)" to the Python module path setting in "''Extras''" → "''Settings''" → "''External Script Interpreters''" → "''Python''", and import it in the Python code as in the previous example.

=== Example 4: Using the Python Appium Bindings ===
In the following, we'll use a Python Appium interface for automation of a mobile application
(in this case, not using the mobile plugin, and not using the GUI Browser).
This may be a useful scenario, if you already have python test actions, which you want to integrate into
expecco.

First install the required python package(s) via the command line or via expecco's "''Plugin''" → "''Bridges''" → "''Python''" menu:
pip3 install Appium-Python-Client
or:
python -m pip install Appium-Python-Client
then make a dummy BridgePython block to check if the package is found:
import appium

def execute():
Transcript.showCR ("Hello world; Appium was found");
Now take either existing code, or copy-paste samples from the [https://pypi.org/project/Appium-Python-Client Appium-Python-Client website]; here is a typical code fragment (of course, you have to adjust the values as required). Obviously, it is also a good idea to add input pins to the python action, so the capabilities and connection parameters can be passed as arguments.
from appium import webdriver

desired_caps = dict(
platformName='Android',
platformVersion='10',
automationName='uiautomator2',
deviceName='Android Emulator',
)

def execute():
driver = webdriver.Remote('http://localhost:4723/wd/hub', desired_caps)
el = driver.find_element_by_accessibility_id('item')
el.click()

=== Example 5: Interfacing to Tensorflow ===

* Create a bridged Python action containing the following code:
import numpy as np
import tensorflow as tf
import tensorflow_hub as hub
import tensorflow_datasets as tfds

def execute():
print("Version: ", tf.__version__)
print("Eager mode: ", tf.executing_eagerly())
print("Hub Version: ", hub.__version__)
print("GPU is", "available" if tf.config.experimental.list_physical_devices("GPU") else "NOT AVAILABLE")

* run it
* if you get a "module not found" error message, either click on the link (named "here"), embedded in the error message, or alternatively select the "''Plugins''" → "''Bridges''" → "''Python''" → "''Install pip Package''" menu item. Of course, you can also install packaged from the command line in a shell/cmd window.
* install missing packages (care for the correct virtual environment if you use them)
* repeat running it, until you get an output on the Transcript (or stderr) similar to:
1: Version: 2.4.1
1: Eager mode: True
1: Hub Version: 0.11.0
1: GPU is NOT AVAILABLE

* You may have to shutdown the bridge after installation of new packages (although it usually works without, unless existing and already loaded packages are upgraded during the installation).

=== Example 6: Interfacing to the "astropy" Package ===
The "astropy" package contains a number of very useful functions for astronomy applications. Among others, you'll find time functions, geo-location mapping, physical constants, image processing and much more inside. (see https://docs.astropy.org/en/stable/index.html)

===== Installation =====

First install the required python package(s) via the command line or via expecco's "''Plugin''" → "''Bridges''" → "''Python''" menu:
pip3 install numpy
pip3 install astropy (astropy-Python-Client)
or:
python -m pip install numpy
python -m pip install astropy (astropy-Python-Client)

===== Smoke Test if Package is Installed =====

then make a dummy BridgePython block to check if the package is found:
import astropy

def execute():
Transcript.showCR ("Hello world; astropy was found");

Notice: because bumpy and astropy are relatively big packages, the first initial execution may take a few seconds because the Python interpreter has to load these packages (but this only happens when the very first Python action is executed).

===== Interface to an astropy Function =====

The following example demonstrates how to call functions within astropy;
this will convert an expecco timestamp (a DateTime object) to a julianDate (as Float).
(Hint: JulianDates are commonly used in Astronomy and Space Sciences).

Please read https://docs.astropy.org/en/stable/time/index.html for details on time functions.

The code includes a few debug prints (to the Transcript). In a production suite, these should probably be commented (or replaced by calls to a logger, which can be switched on/off dynamically).

[[Datei:AstroPyExample1.png|500px]]

The action can then be used in a diagram as:

[[Datei:AstroPyExample2.png|500px]]

After a run, we get the Julian date as a float:

[[Datei:AstroPyExample3.png|500px]]

Be aware that expecco requires objects to be JSON serializable to be passed from/to the Python interpreter. Sadly, this is not true for all atrophy objects. If required either pass objects by reference or encode/decode them as strings (or extract subfields into an array and pass the array or pass subfields via individual input/output pins).

It may also be possible to define additional JSON encoders/decoders for individual types.

=== Example 7: Background Thread Inside Python ===

It may be useful to execute python code in a Python background thread;
for example to poll for data or to check for external equipment status
in a loop.

===== Extra Process with a Secondary Python Bridge =====

In many cases, you can start a secondary Python bridge and execute actions
in it via an expecco background action.
 For this:
* start a new Python bridge (using the "[Python] Start bridge" action from the standard library) in the background action
* add a python bridge input pin to actions which are to be executed there and pass that bridge reference to the background action's python step inputs.
:As an alternative, define an environment variable named "PYTHON" in the background action and set its value to the second bridge instance. Then all python actions inside and under the bg-action will be executed there.
Notice that no object references can be exchanged between the two bridges;
you are limited to data types which are JSON representable.

===== Thread inside the Same Python Bridge =====
If the above is not feasable (for example because the background actions needs access to values or handles of the other actions), you can start a thread inside the same bridge.

However, a number of have to be considered:
* ensure that the extra thread can be terminated eventually. Because Python does not provide a kill-thread mechanism, the thread must check for a stop variable, and terminate itself.
* the stop variable should not be a Python global, to avoid name conflicts if more than one background thread is started (or another imported library uses a similar mechanism)
* communication with the background thread must be performed via event queues, because it cannot write to any output pin.

Here is an example which follows the above scheme:
====== Background Thread Starter ======
[[Datei:Python_background_action_schema.png|mini]]
A Python action which gets a bridge and additional parameters as input. Here, a deltaTime, which defines the poll-loop cycle and a token which is passed with the checkStatus to the event queue.

The action defines 3 functions, the threaded function itself, for which a new thread is started by "execute", and a thread-stop function (which simply sets the "running" variable to False.

A reference to the stop-function is sent to the output pin.

import sys
import time
import threading

running = True

def thread_function(dt, tok):
nonlocal running

ExpeccoLogger.info("Thread %s: starting", tok)
while running:
time.sleep(dt)
if running:
checkOutcome = True # perform check...
pushEventType_data("bg-check", (tok,checkOutcome))
ExpeccoLogger.info("Thread %s: finishing", tok)

def stopThread():
nonlocal running
ExpeccoLogger.info("stopThread")
running = False

def execute():
ExpeccoLogger.info ("start")
x = threading.Thread(target=thread_function,
args=(waitTime.value(), token.value(),))
x.start()
stopper = stopThread
stopThreadOut.value(makeRef(stopThread))
ExpeccoLogger.info ("end")

====== Thread Stopper ======
[[Datei:Call_Python_Function.png|mini]]
the stop-function provided by the thread-starter can later be called to clear the "running" flag. An action to call it would look like:

import threading

def execute():
f = func.value()
f()

====== EventQueue Setup ======
The background thread will write to an event queue, with its events marked as 'bg-check'. Thus, we must define a handler for those events.
In expecco, a handler can be either an action block, or a Smalltalk block or a JavaScript function.
 This example uses a Smalltalk block which send a message to the Transcript:
[[Datei:Python_BG-Thread-Setup.png]]
When executed, the Transcript shows:
[info]: start {SimpleBridge >> event_LOGGER: [78]}
[info]: Thread action1: starting {SimpleBridge >> event_LOGGER: [78]}
[info]: end {SimpleBridge >> event_LOGGER: [78]}
Event(type=bg-check data=#(action1 true) ts=2024-04-29 16:11:49.907)
Event(type=bg-check data=#(action1 true) ts=2024-04-29 16:11:50.909)
Event(type=bg-check data=#(action1 true) ts=2024-04-29 16:11:51.914)
Event(type=bg-check data=#(action1 true) ts=2024-04-29 16:11:52.919)
Event(type=bg-check data=#(action1 true) ts=2024-04-29 16:11:53.937)
[info]: stopThread {SimpleBridge >> event_LOGGER: [78]}
[info]: Thread action1: finishing {SimpleBridge >> event_LOGGER: [78]}

=== Example 8: Interfacing to a .NET Assembly via IronPython ===

IronPython is a python interpreter running within the .NET CLR framework. The ability of IronPython to import .NET assemblies, makes it easy to also interface those to expecco.

Please refer to the IronPython documentation on how to import .NET assemblies.

 --- example to be added ---

== Bridged C Elementary Blocks ==

The following works in 19.2 and above. 
You have to make sure that a C-compiler toolchain is available and can be called directly or indirectly (see [[Installing_additional_Frameworks/en | "Installing additional Frameworks"]]).

Bridged C-code is highly dependent on the C-compiler toolchain of the target machine and may require preparations for machine dependencies with #ifdefs (word length, OS-APIs etc.). It is typically used by experts and for special situations, when simpler alternatives are not available.

Bridged C-code can be used to implement time critical functions or to interface to C/C++ libraries, when the simple DLL-call interface is too complicated to use (for example, if complicated data structures have to be exchanged, if C-callbacks are needed, or if C++ interfaces are to be implemented).

In addition, bridged C-Code actions run in a separate process, isolated from expecco. Thus expecco is not affected by errors in the C-code and cannot be disturbed (eg. by invalid memory references), which is not guaranteed for DLL called functions (which are executed within the expecco process). On the downside, there is some overhead involved in calling a bridged action, since input/output parameters and the call itself are transmitted via an interprocess communication mechanism (i.e. socket/network message). Thus the call roundtrip times are in the millisecond range, as opposed to microseconds for DLL calls.

Other applications are high-speed data acquisition and protocol implementations, in which a C-part is responsible for the time critical task, and expecco can query/control that task remotely (i.e. fetch captured data or state information).

=== The C Bridge ===
Be reminded that bridged C-Code actions are executed inside a separate OS-process, which runs the c-bridge code.
Whenever a bridged C-action is to be executed, the pin-data is transferred via an interprocess communication mechanism (IPC), and the code executed inside the bridge process. Pin data and event requests are transmitted back to expecco via the same IPC mechanism.

The C-bridge itself is available as executable or as shared or linkable library in two configurations, with or without the dynamic C code injection facility.

Setups without code injection are useful to augment (statically compiled) embedded systems with a debug interface, through which expecco can later access specific (and explicitly published) interfaces. In such a setup, no dynamic C-code can be injected into the running application. Instead, the set of callable interfaces must be declared and implemented in advance (in the embedded system).

The following chapter describes the dynamic C-code injection facility as seen by elementary activity code in expecco. For static embedded systems, please refer to the [[Embedded Systems C Bridge API | "Embedded Systems C Bridge API"]].

=== Bridged C Code API ===

Note: This is a preliminary API documentation. Bridged C elementary actions are still being developed and the API may be extended or improved in the future (However, it is very very likely to be backward compatible).

The API is intended to look similar to the other languages' elementary code API.
However, due to the nature and syntax of the C-language, certain differences are apparent. 
The biggest differences are due to C being a statically typed language: the simple "<code>pin.value()</code>" interface for pins (as used in other languages) cannot be offered here; instead, a datatype-specific API is provided in C.

==== Variables Seen by the Executed C Function ====

The following variables are in the scope of the executed function:

*<code>Transcript</code> supports a few functions to display messages in the expecco Transcript window (used as argument; see below)
*<code> Stdout </code> supports a few functions to display messages on expecco's stdout stream (used as argument; see below). This is NOT the same as the stdout FILE*.
*<code> Stderr </code> supports a few functions to display messages on expecco's stderr stream (used as argument; see below). This is NOT the same as the stderr FILE*.


==== Reporting (C) ====

*void '''error''' (char* ''fmt'' , ...) Report a defect (in the test). Stops execution. The arguments are printf-style.

*void '''fail''' (char* ''fmt'', ...) Report a failure (in the SUT). Stops execution. The arguments are printf-style.

*void '''inconclusive''' (char* ''fmt'' , ...) Report an inconclusive test. Stops execution. The arguments are printf-style.

*void '''activitySuccess''' (char* ''fmt'' , ...) Finishes the current activity with success (same as "success()"). The arguments are printf-style.

==== Logging (C) ====

*void '''logFail''' (char* ''fmt'' , ...) Adds a fail message to the activity log, but continues execution. The arguments are printf-style. Notice: although the action continues to be executed, it will be marked as failed at the end.

*void '''logError''' (char* ''fmt'' , ...) Adds a error message to the activity log, but continues execution. The arguments are printf-style. Notice: although the action continues to be executed, it will be marked as erronous at the end.

*void '''logWarning''' (char* ''fmt'' , ...) Adds a warning to the activity log, but continues execution. The arguments are printf-style.

*void '''logInfo''' (char* ''fmt'' , ...) Adds an info message to the activity log, and continues execution. The arguments are printf-style.

*void '''alert''' (char* ''fmt'' , ...) Adds a warning message to the activity log, and also shows a DialogBox, which has to be confirmed by the operator. The dialog box and confirmation can be disabled by a settings flag in the "''Execution''" → "''Log -Settings''" dialog (by default it is disabled).

*void '''warn''' (char* ''fmt'' , ...) Same as alert(). (For Smalltalk protocol compatibility)

==== Event Sending (C) ====
*void '''pushEventType_data'''(char* ''event'', char* ''dataOrNULL'') adds an event to expecco's event queue. The payload in ''dataOrNULL'' must be a 0-terminated string.

*void '''pushEventType_dataBytes'''(char* ''event'', unsigned char* ''dataOrNULL'', int ''numBytes'') adds an event to expecco's event queue. The payload in ''dataOrNULL'' points to a byte-buffer of given length.

*void '''pushEventType_dataJSON'''(char* ''event'', jsonObject ''dataOrNULL'') adds an event to expecco's event queue. The payload in ''dataOrNULL'' is a [[Embedded_Systems_C_Bridge_API#JSON_Library|json object]].


==== Pin Functions (C) ====
Currently, C blocks do not support a variable number of input or output pins.

Attention:
 C uses many more reserved keywords for syntax than Smalltalk. These keywords cannot be used as pin names, and you will get a syntax error if you try. Be careful to not name your pins as any of: "<code>return</code>", "<code>char</code>", "<code>int</code>", etc.

As a proven best practice, add a "''Pin''" suffix to your pin names (e.g. name it "''inPin''", instead of "''in''").

===== Input Pins (C) =====

====== Queries ======
*bool_t '''hasValue''' (''inPin'') Returns true if the pin has received a value, where ''true'' is represented as 1, false as 0.

*bool_t '''isConnected''' (''inPin'') Returns true if the pin is connected.

====== Pin Value ======
'''Scalar Values''' 
*char* '''stringValue''' (''inPin'') Returns the string value at the pin as a c-char*. Raises an error if the pin did not receive a value, or if the value was not a string. The returned pointer becomes invalid after the action's execution; it should therefore be strcpy'd if it is needed later (i.e. do not keep a reference to it).

*long '''longValue''' (''inPin'') Returns the integer value at the pin as a c-long. Raises an error if the pin did not receive a value, or if the value was not an integer.

*longlong '''longLongValue''' (''inPin'') (vsn24.1, 64bit) Returns the integer value at the pin as a c-longLong. Raises an error if the pin did not receive a value, or if the value was not an integer. This API is only avalable in 64bit versions of the C-bridge (i.e. not in the cBridge32.exe for Windows) and only with expecco vsn 24.1 and later.

*double '''doubleValue''' (''inPin'') Returns the double value at the pin as a c-double Raises an error if the pin did not receive a value, or if the value was not a number.

*bool_t '''booleanValue''' (''inPin'') Returns the boolean value at the pin as a c-int. Raises an error if the pin did not receive a value, or if the value was not a boolean.

'''Vectors''' (aka Arrays) 
*uchar* '''bytesValue''' (''inPin'') Returns the byteArray value at the pin as a c-unsigned char*. Raises an error if the pin did not receive a value, or if the value was not a byteArray or C-struct. This can also be used to receive other bulk data, such as an int32 or float array. For example, by converting a collection of numbers first to a byteArray, and then casting the bytesValue to another pointer type in the bridge code. Use arraySize to get the number of bytes in the byte[]. [[bild:bulb.png|20px]]Attention: the returned array has been allocated with malloc() on the heap, and will be freed after the request. If you need to keep it (for whatever reason), it must be copied to a static or another malloc'd memory area.

*ushort* '''shortsValue''' (''inPin'') Returns the shortArray value at the pin as a c-unsigned short*. Raises an error if the pin did not receive a value, or if the value was not an array. Use arraySize to get the number of shorts in the short[]. [[bild:bulb.png|20px]]Attention: the returned array has been allocated with malloc() on the heap, and will be freed after the request.

*uint* '''intsValue''' (''inPin'') Returns the intArray value at the pin as a c-unsigned int*. Raises an error if the pin did not receive a value, or if the value was not an array. Use arraySize to get the number of ints in the int[]. [[bild:bulb.png|20px]]Attention: the returned array has been allocated with malloc() on the heap, and will be freed after the request.

*float* '''floatsValue''' (''inPin'') Returns the floatArray value at the pin as a c-float*. Raises an error if the pin did not receive a value, or if the value was not an array. Use arraySize to get the number of floats in the float[]. [[bild:bulb.png|20px]]Attention: the returned array has been allocated with malloc() on the heap, and will be freed after the request.

*double* '''doublesValue''' (''inPin'') Returns the doubleArray value at the pin as a c-double*. Raises an error if the pin did not receive a value, or if the value was not an array. Use arraySize to get the number of doubles in the double[]. [[bild:bulb.png|20px]]Attention: the returned array has been allocated with malloc() on the heap, and will be freed after the request.

'''Other''' 
*void* '''pointerValue''' (''inPin'') Returns the pointer value at the pin as a void*. This must be a pointer which has been previously sent to expecco via putPointer(). Raises an error if the pin did not receive a value, or if the value was not a pointer. This means, that it must be a pointer as previously sent to expecco with putPointer. Please read the description of "putPointer()" below.

*jsonObject '''jsonValue''' (''inPin'') Returns the value at the pin as a [[Embedded_Systems_C_Bridge_API#JSON_Library|jsonObject]]. Raises an error if the pin did not receive a value. [[bild:bulb.png|20px]]The returned pointer becomes invalid after the action's execution; field values should therefore be extracted and copied if needed later (i.e. do not keep a reference to it or its components).

'''Queries''' 
*int '''arraySize''' (''inPin'') Returns the number of array elements, if there is a byte-, short-, int-, float- or double-Array at the pin. Raises an error if the pin did not receive a value, or if the value was not an array or C-struct.

'''Values with Default'''
*char* '''stringValueIfAbsent''' (''inPin'', char* ''repl'') Returns the pin's datum if it has one, ''repl'' otherwise. Similar to "<code>stringValue()</code>", but avoids the exception. The returned pointer becomes invalid after the action's execution.

*long '''longValueIfAbsent''' (''inPin'', long ''repl'') (vsn24.1, 64bit) Returns the pin's datum if it has one, ''repl'' otherwise. Similar to "<code>longValue()</code>", but avoids the exception.

*longlong '''longLongValueIfAbsent''' (''inPin'', longlong ''repl'') Returns the pin's datum if it has one, ''repl'' otherwise. Similar to "<code>longLongValue()</code>", but avoids the exception. This API is only avalable in 64bit versions of the C-bridge (i.e. not in the cBridge32.exe for Windows) and only with expecco vsn 24.1 and later.

*double '''doubleValueIfAbsent''' (''inPin'', double ''repl'') Returns the pin's datum if it has one, ''repl'' otherwise. Similar to "<code>doubleValue()</code>", but avoids the exception.

*bool_t '''booleanValueIfAbsent''' (''inPin'', bool_t ''repl'') Returns the pin's datum if it has one, ''repl'' otherwise. Similar to "<code>booleanValue()</code>", but avoids the exception.

*uchar* '''bytesValueIfAbsent''' (''inPin'', uchar* ''repl'') Returns the pin's datum if it has one, ''repl'' otherwise. Similar to "<code>bytesValue()</code>", but avoids the exception.

*jsonObject '''jsonValueIfAbsent''' (''inPin'', jsonObject ''repl'') Returns the pin-datum as a [[Embedded_Systems_C_Bridge_API#JSON_Library|jsonObject]] if it has one, ''repl'' otherwise. Similar to "<code>jsonValue()</code>", but avoids the exception. The returned pointer becomes invalid after the action's execution.

*char* '''stringValueIfPresent''' (''inPin'') Returns the pin's datum if it has one, an empty string otherwise. Similar to "<code>stringValue()</code>", but avoids the exception. The returned pointer becomes invalid after the action's execution.

*long '''longValueIfPresent''' (''inPin'') Returns the pin's datum if it has one, 0 (zero) otherwise. Similar to "<code>longValue()</code>", but avoids the exception.

*longlong '''longLongValueIfPresent''' (''inPin'') (vsn24.1, 64bit) Returns the pin's datum if it has one, 0 (zero) otherwise. Similar to "<code>longLongValue()</code>", but avoids the exception. This API is only avalable in 64bit versions of the C-bridge (i.e. not in the cBridge32.exe for Windows) and only with expecco vsn 24.1 and later.

*double '''doubleValueIfPresent''' (''inPin'') Returns the pin's datum if it has one, 0.0 (zero) otherwise. Similar to "<code>doubleValue()</code>", but avoids the exception.

*bool_t '''booleanValueIfPresent''' (''inPin'') Returns the pin's datum if it has one, 0 (false) otherwise. Similar to "<code>booleanValue()</code>", but avoids the exception.

*uchar* '''bytesValueIfPresent''' (''inPin'') Returns the pin's datum if it has one, NULL otherwise. Similar to "<code>bytesValue()</code>", but avoids the exception.

*jsonObject '''jsonValueIfPresent''' (''inPin'') Returns the pin-datum as a [[Embedded_Systems_C_Bridge_API#JSON_Library|jsonObject]] if it has one, NULL otherwise. Similar to "<code>jsonValue()</code>", but avoids the exception. The returned pointer becomes invalid after the action's execution.

Variable number of input/output pins are not supported. You should pass an array or structure if required.

===== Output Pins (C) =====

* void '''putString''' (''outPin'', char* ''data'') Writes a string to the output pin. The string must be zero-terminated.

* void '''putStringN''' (''outPin'', char* ''data'', int ''len'') Writes len bytes of a string to the output pin.

* void '''putLong''' (''outPin'', long ''data'') Writes a long to the output pin. Be aware that the size of a long depends on the cbridge host's CPU architecture, the OS and the C-compiler: on Unix machines, it is typically an int64, whereas on Windows it is usually an int32.

* void '''putULong''' (''outPin'', unsigned long ''data'') Writes an unsigned long to the output pin. Be aware that the size of an unsigned long depends on the cbridge host's CPU architecture, the OS and the C-compiler: on Unix machines, it is typically an uint64, whereas on Windows it is usually an uint32.

* void '''putLongLong''' (''outPin'', long long ''data'') Writes a long long to the output pin. Typically, a long long is an int64 on all architectures.

* void '''putULongLong''' (''outPin'', unsigned long long ''data'') Writes an unsigned long long to the output pin. Typically, an unsigned long long is an uint64 on all architectures (depends on cbridge host's CPU, OS and compiler). This API is not available in the 32 bit cBridge version.

* void '''putDouble''' (''outPin'', double ''data'') Writes a double (float64) to the output pin.

* void '''putBoolean''' (''outPin'', bool_t ''data'') Writes a boolean to the output pin. Anything but 0 (zero) is interpreted as true.

* void '''putJsonObject''' (''outPin'', jsonObject ''data'') Writes a [[Embedded_Systems_C_Bridge_API#JSON_Library|jsonObject]] to the output pin. Refer to [[Embedded_Systems_C_Bridge_API#JSON_Library | the JSON library documentation]] on how to create a [[Embedded_Systems_C_Bridge_API#JSON_Library|jsonObject]].

* void '''putBytesN''' (''outPin'', unsigned char* ''bytes'', int ''nBytes'') Writes nBytes from a byte array to the output pin.

* void '''putPointer''' (''outPin'', void* ''dataPtr'') Writes a reference for dataPtr to the output pin. This value can be passed to another cBridge action (executed on the same bridge), where it can be read from the input with <code>pointerValue()</code> (this is similar to the makeRef mechanism of other bridged languages).

The following API will be available with the 21.2 release:

* void '''putDoublesN''' (''outPin'', double* ''doubles'', int ''count'') Writes count double values as a vector to the output pin. expecco will receive these values as a collection of double precision floating point values.

* void '''putFloatsN''' (''outPin'', float* ''floats'', int ''count'') Writes count float values as a vector to the output pin. expecco will receive these values as a collection of single precision floating point values.

* void '''putIntsN''' (''outPin'', int* ''ints'', int ''count'') Writes count int values as a vector to the output pin. expecco will receive these values as a collection of integer values.

* void '''putLongsN''' (''outPin'', long* ''longs'', int ''count'') Writes count long values as a vector to the output pin. expecco will receive these values as a collection of integer values. Be reminded that the sizeof longs may be different between Windows and non-Windows machines.

These vectors will appear at the output pin as a collection; the type of collection is given by the pin's datatype. For most space efficient representation, we recommend the use of the bulk data types (FloatArray, DoubleArray, etc.)

The following API will be available with the 21.2.1 update release:

* void '''putShortsN''' (''outPin'', short* ''longs'', int ''count'') Writes count (signed) short values as a vector to the output pin. expecco will receive these values as a collection of integer values.

* void '''putUIntsN''' (''outPin'', unsigned int* ''ints'', int ''count'') Writes count unsigned int values as a vector to the output pin. expecco will receive these values as a collection of integer values.

* void '''putULongsN''' (''outPin'', unsigned long* ''longs'', int ''count'') Writes count unsigned long values as a vector to the output pin. expecco will receive these values as a collection of integer values. Be reminded that the sizeof longs may be different between Windows and non-Windows machines.

* void '''putUShortsN''' (''outPin'', unsigned short* ''longs'', int ''count'') Writes count unsigned short values as a vector to the output pin. expecco will receive these values as a collection of integer values.

==== Transcript, Stderr and Stdout (C) ====

The expecco "<code>Transcript</code>", "<code>Stderr</code>" and "<code>Stdout</code>" are also accessible from C code (as pseudo variables).
However, only a very limited subset of operations is supported (in the following, ''stream'' stands for one of the above wellknown expecco streams and is given as argument to the function):

*void '''cr''' (''stream'') Adds a linebreak (i.e. followup text will be shown on the next line)

*void '''show''' (''stream'', char* ''fmt'', ...) Adds a textual representation of the argument. The argument is printf-style.

*void '''showCR''' (''stream'', char* ''fmt'', ...) A combination of show(), followed by a linebreak.

If the bridge was started by expecco (as opposed to being executed on a remote host), stdout and stderr are also forwarded to the expecco Transcript window, depending on the settings in expecco ("''Extras''" → "''Settings''" → "''Execution''" → "''Tracing''" → "''Show Stdout and Stderr on Transcript''").

Thus, you can use "<code>fprintf(stdout, ...)</code>" or "<code>fprintf(stderr, ...)</code>" or "<code>showCR(Transcript, ...)</code>".
 

==== Additional Utility Functions (C) ====

*char* '''getTmpDirectory''' () Returns a pointer to the pathname of the temp directory.

*char* '''getenv''' (char* ''varName'') Returns a pointer to the shell variable's value.

*int '''setenv''' (char* ''varName'', char* ''value'') Set the shell variable's value.

=== Referring to Functions in Shared Libraries ===

If the cBridge code refers to any functions which are located in additional shared libraries (DLLs), the bridge needs to know where to find those.

The location of any shared library must be specified in the C-bridge settings dialog, unless the library is found in the CBridge executable's folder or at a standard place (eg. "/usr/lib", "/usr/local/lib", etc. on Unix and "C:\Windows" and others on Windows).
The details depend on the OperatingSystem; Windows searches along the PATH setting, linux along LD_LIBRARY_PATH. If in doubt, consult your OS documentation.

Navigate to "''Extras''" → "''Settings''" &#rarr; "''Execution''" &#rarr; "''External Script Interpreters''" &#rarr; "''CBridge''" and add the path to the "DLL Path" field.

As an alternative, edit the CC-Script and add appropriate command line arguments to the linker command near the end (it is recommended to keep the original, and make an edited copy).

You'll also have to edit the script, if additional compiler or linkage arguments are required, or if you have to determine the location of additional frameworks dynamically.

=== Referring to Types Defined in expecco ===

User defined struct, union and enum "CType (C-Defined)" dataypes (which are declared in expecco and present in the suite's element tree) are visible inside the activity code, and can be included as:
#include "expecco/Types/XXX.h"
where "XXX" is the name of the expecco type (in the tree).
If the type declares an unnamed struct, the type will be known as a typedef in the C-code.
==== Typedef Name vs. struct/union Name ====
If the type is named "myStruct" and defined as:
struct {
...
}
it should be referred to in the C-code as:
myStruct s, *sP;
In this case, the name of the typedef is the name of the type.

In contrast, if it was defined as:
struct foo {
...
}
you can also write:
struct foo s;
struct foo *sP;
In other words, there will be a typedef for "myStruct" (the name of the type) and a struct by the name as in the type's definition.

Notice, that these files do actually not exist; instead, the activity's C-code is scanned and dynamically expanded to include those definitions. See example below.
You should shutdown any already running bridge, when a type is changed, to enforce a recompilation of the C code.

=== Including Attachments as Header Files ===

Attached files can be included as:
#include "expecco/Attachments/XXX.h"
where "XXX.h" is the name of the expecco attachment file.
 Be reminded that the name of the attachment itself (the tree-item name) is not required to be the same as the name of the file, although usually, they are.

=== C++ Interfaces ===
C++ functions should be called indirectly via a C function wrapper (i.e. <code>extern "C"</code>).
 Object references can be passed from the bridge to expecco and back via the "<code>putPointer</code>" and "<code>pointerValue</code>" functions.

=== Running Bridged C-Code on a Remote Computer ===

The remote computer must have the cBridge executable running.
The executable is found in the "<code>packages/bridgeFramework/cBridge/cLibrary</code>" folder under your expecco installation folder and should be copied to the remote machine. Windows users will find both a 64bit version ("cBridge.exe") and a 32bit one ("cBrige32.exe"). If your C-code needs or refers to any existing dll, make sure that the correct bridge is configured in the settings (a 32bit bridge will not be able to load a 64bit dll and vice versa).

On the expecco side, you have two options:
# specify that the bridge is already running in the settings; then all cBridge actions which have not been explicitly given a bridge to execute in will be executed there
# explicitly connect to a running bridge via the "''Connect to Running Bridge''" action block, and passing the resulting bridge handle to the C-action.
The handle can be passed either explicitly via the step's cBridge input pin, or implicitly by declaring a variable named "CBRIDGE" and storing the handle there. The cBridge input pin is generated via the step's ''Special Pins'' menu.

Bridges can be started either by one of the bridge start actions in the standard library or by a batch-, shell- or powershell script. Type "<code>cBridge --help</code>" for command line options.

You can have multiple bridges running, even in heterogenous networks (i.e. call for a remote C-action on a Windows machine, while running expecco on a Linux machine).
We provide bridge executables for additional architectures (eg. Raspberry-PI) upon request and for a small additional fee.

=== Running Multiple Bridges in Parallel ===

You can start multiple bridges via the "[Start new local CBridge]" action from the standard library and remember the bridge connection handles in variables. 
[[Datei:Setup.png|300px]] Make sure, that the bridges are using different ports.

In addition, add a bridge input pin to the action(s) which you want to execute on one of those bridges (via the "Special Pins" popup menu in the action's schema). [[Datei:ShowTempDir.png|300px]] 
For example, the following simply sends a message to the standard error:
static void
execute() {
char buffer[128];

snprintf(buffer, sizeof(buffer), "%s", getTmpDirectory());
putString(output, buffer);
}
and finally, here is an example which executes this action in parallel on
4 bridges: [[Datei:FourActions.png|300px]].

=== Bulk Data ===

If a huge number of data elements (known as "''Bulk Data''") are to be transferred, transmission times may get much longer than the actual execution time of the action (keep in mind that the communication times take most of the time if the executed computation is simple).

There are multiple possible ways to deal with this situation:

* Passing a Pointer to expecco
:if you can leave the data inside the bridge (eg. as malloc'd data vector), '''and''' expecco does not need to access the elements of the vector, you can leave the data inside the cBridge and only pass a handle to expecco. This handle may later be sent to another C-action to process the data at non-critical times (eg. at the end of the test).
:This mechanism is the fastest because only a small handle (typically 32/64 bits) has to be transmitted to expecco. However, it degrades to become very very slow if you access individual elements of the vector from expecco, as this will result in one IPC roundtrip per accessed element.
* Passing Bulk Data as a Vector
:If each vector element is sent individually to an output pin (i.e. in a loop with putFloat()/putDouble()), one IPC roundtrip will be performed per element.
:It is much faster to send the whole vector data sent as one array via putDoublesN(), putFloatsN() or putIntsN(). This still does introduce some additional cost due to JSON-encoding (on the cBridge side) and JSON-decoding on the expecco side, but the effective transmission time is dramatically reduced.
* Passing Bulk Data as a ByteArray
:Further speedup is possible by not sending the data as a number vector, but instead as a byte vector, actually sending the raw ended bytes from the bridge to expecco. For this, use a putBytesN() call and case your bulk data to a "char *".
:However (big warning): expecco will receive a byte-vector and you will have to add code to extract the relevant elements from this. If the cBridge CPU and the expecco-CPU use a different byte order or a different floating-point-number representations, you will have to deal with that in that extraction code. Be aware, that it may even depend on the compiler: Microsoft VisualC compilers for x86_64 interpret "long" as a 32bit integer, whereas most other compilers/systems treat them as 64bit integers. 
:This is probably the fastest method to transmit bytes, but comes with those possible pitfalls. We therefore recommend to try the "Bulk Data as Vector" method first. In most situations that is either within the acceptable timing constraints, or too far off, such that the ByteArray transmission will also not be fast enough, and you should use the pointer passing method anyway.

If the cBridge runs on the same machine as expecco, shared memory will be used to exchange bulk data. This may reduce the transmission times drastically, depending on the amount of data (there are still other messages exchanged via the socket communication).

=== Example1: Writing and Calling C Code in Expecco ===

In this example, numbers and a string will be passed to a C action block. The action has been defined with 3 input pins:
* <code>in1</code> (type Float)
* <code>in2</code> (type Integer)
* <code>in3</code> (type String)
and the single output "<code>out1</code>", with type String.

The code will generate a string by concatenating the printf strings of its arguments at the output
and also print a number of messages via different output channels.

Create a new bridged C action, 
[[Datei:CBridge Demo Action1.png]]
 and enter the code:

static void
execute() {
double dVal = '''doubleValue'''(in1); // fetch input pin's double value
long lVal = '''longValue'''(in2); // fetch input pin's integer value
char* sVal = '''stringValue'''(in3); // fetch input pin's string value
char buffer[512];

snprintf(buffer, sizeof(buffer), "%s / %ld / %g", sVal, lVal, dVal);

// write to output pin
'''putString'''(out1, buffer);

// a regular print
// (will be shown inside expecco's Transcript, if io-trace is enabled)
fprintf(stderr, "hello on stderr from C-Code!\n");

// another regular print
// (will be shown inside expecco's Transcript, if io-trace is enabled)
fprintf(stdout, "hello on stdout from C-Code!\n");
// explicit output to expecco's Transcript

// explicit output to expecco's stdout
'''show'''(Stdout, "hello on expecco's stdout from C-Code!\n");

// explicit output to expecco's stderr
'''show'''(Stderr, "hello on expecco's stderr from C-Code!\n");

// explicit output to expecco's Transcript
'''show'''(Transcript, "another hello from C-Code!\n");

// possibly report failure to expecco
if (strlen(sVal) < 20) {
'''fail'''("short string \"%s\" (length=%d)", sVal, strlen(sVal))
}
}

=== Example2: Passing Complex Objects to and from C-Code (by value) ===

Complex struct objects can be passed by value to the C-code by defining a CStruct type
i.e. create a new type named eg. "myStruct" in the tree, define it as C-Type and enter a definition similar to:

/* C: */
struct {
int i1;
float f1;
double d1;
char c[20];
}

then, add an input pin with that datatype to the C-action,
and add the following line to the action's C-code, to include the type's definition:

#include "expecco/Types/myStruct.h"

(the name of the include must match the type's typename in the tree)

From within your C-code, access the fields with:

struct myStruct* p;

p = (struct myStruct*)'''bytesValue'''(inPin);

fprintf(stderr, "got i1:%d\n", p->i1);
fprintf(stderr, "got f1:%f\n", p->f1);
fprintf(stderr, "got d1:%F\n", p->d1);
fprintf(stderr, "got c:%s\n", p->c);

and write such a struct to an output pin with:

'''putBytesN'''(outPin, p, sizeof(struct myStruct));

To create such a struct argument, use an instance creation action block (and possibly additional field setter actions).
Those can be automatically generated by selecting the type in the tree,
and invoking the popup menu function "''Refactoring''" → "''Generate''" → "''Creators and Accessors''".

=== Example3: Passing Handles/Pointers to expecco and Back to Another C Action ===

A common situation is when two C actions are given, where one generates a handle (i.e. pointer),
which must be passed to the other action (in the same bridge).
 For example, the first may be a "<code>createConnection()</code>" function,
and the second needs that connection handle as argument (that would typically be a kind of "<code>send()</code>", "<code>receive()</code>" or "<code>close()</code>" function, and the handle something like a FILE pointer or Windows handle).

For this scenario, the cBridge provides a mechanism similar to the "<code>makeRef</code>" facility of other bridges.
The first action function will send the handle to an output pin via "<code>putPointer()</code>";
the pin's datatype should be "<code>Any</code>", "<code>Handle</code>" or a struct type as described above:

void execute() {
...
'''putPointer'''( outPin, (void*) handle );
}

and the other action functions can get this handle from an input pin:

void execute() {
handle = '''pointerValue'''( inPin );
...

=== Example4: Passing Bulk Data to expecco and to another C Action ===

In this example, one generates some data (eg. a vector of float values),
and passes this to another C action (possibly in another bridge).
 For example, the first may be a measurement value collector,
and the second computes some statistical analysis.
Be aware, that this example was created for demnstration; in practice, you would probably pass a pointer within the same bridge. But the example is also useful if one of those actions is a non-C action, for example a Python numpy action.

The first action function generates some data and sends them to an output pin.
The pin's datatype should be "<code>float*</code>" or "<code>FloatArray</code>":

#define NUM_FLOATS 1024 // or whatever
void execute() {
float data[NUM_FLOATS];
...
// compute or generate the data
for (i=0; i<NUM_FLOATS; i++) {
data[i] = ...
}
...
// send it to the output pin
'''putFloatsN'''( outPin, data, NUM_FLOATS );
}

the receiving action can get this data from an input pin (also with type "<code>float*</code>" or "<code>FloatArray</code>"):

void execute() {
float* data;
int numElements;

// receive from an input pin
// always verify the size!
// The data could have been created by any action with any size!
data = '''floatsValue'''( inPin );
numElements = '''arraySize'''( inPin );
...
// processing
for (i=0; i<numElements; i++) {
... do something with data[i] ....
}
...
}

== Bridged Smalltalk Elementary Blocks ==

The following works in 20.1 and above. 
Similar to the above described bridged Node and bridged Python actions, these actions are coded in the Smalltalk language and executed by a separate Smalltalk engine (separate process). Both local and remote execution are possible.

By the time of writing, bridged Smalltalk actions can be executed in an ST/X Smalltalk engine, support for VA-Smalltalk and VW-Smalltalk is being developed and will be available in one of the next expecco releases.

=== Bridged Smalltalk Code API ===

Note: This is a preliminary API documentation.
Bridged Smalltalk elementary actions are still being developed and the API may change slightly until officially released.

Bridged Smalltalk actions will execute in another Smalltalk system; by the time of writing, this may be another Smalltalk/X or a VisualWorks Smalltalk system. With enough customer interest, other dialects (VisualAge and Squeak) may be supported in the future.

The API looks similar to the API of regular Smalltalk actions, which execute inside expecco itself.
However, for some objects, only a subset of the protocol is available.

==== Variables (Bridged Smalltalk) ====

The following variables are in the scope of the executed code:

*<code>Transcript</code> a proxy which supports a few functions to display messages in the expecco Transcript window (see below)
*<code> Stdout </code> a proxy supports a few functions to display messages on expecco's stdout stream (see below)
*<code> Stderr </code> a proxy supports a few functions to display messages on expecco's stderr stream (see below)

 

==== Reporting (Bridged Smalltalk) ====

*'''error''':''infoString'' [ '''with''':''arg1'' ... '''with''':''arg4'' ] Report a defect (in the test). Up to 4 optional with:-args are sliced into the string, if it contains "%i" placeholders. Stops execution.

*'''fail''':''infoString'' [ '''with''':''arg1'' ... '''with''':''arg4'' ] Report a failure (in the SUT). Stops execution.

*'''inconclusive''':''infoString'' [ '''with''':''arg1'' ... '''with''':''arg4'' ] Report an inconclusive test. Stops execution.

*'''activitySuccess''':''infoString'' [ '''with''':''arg1'' ... '''with''':''arg4'' ] Finishes the current activity with success (same as "success()").

*'''pass''':''infoString'' [ '''with''':''arg1'' ... '''with''':''arg4'' ] Finishes the current testCase with success.
 

==== Logging (Bridged Smalltalk) ====

*'''logFail''':''messageString'' Adds a fail message to the activity log.

*'''logError''':''messageString'' Adds a error message to the activity log.

*'''logWarning''':''messageString'' Adds a warning to the activity log.

*'''logInfo''':''messageString'' Adds an info message to the activity log.

*'''alert''':''messageString'' Adds a warning message to the activity log, and also shows a DialogBox, which has to be confirmed by the operator. The dialog box and confirmation can be disabled by a settings flag in the "''Execution''" → "''Log Settings''" dialog (by default it is disabled).

*'''warn''':''messageString'' Same as ''alert:'' (for JavaScript compatibility).
 

==== Environment Access (Bridged Smalltalk) ====
*'''environmentAt'''(<varName>); Fetches and returns a value from the expecco environment which is in scope of the current activity. You can only read simple objects (numbers, booleans and strings) from remote smalltalk actions.

*'''environmentAtPut'''(<varName>, <newValue>); Writes a value into the expecco environment which is in scope of the current activity. The variable must be writable. You can only write simple objects (numbers, booleans and strings) from remote smalltalk actions.

 

==== Input Pins (Bridged Smalltalk) ====

*''pin'' '''hasValue''' Returns true if the pin has received a value

*''pin'' '''value''' Returns the value of the pin. Raises an error if the pin did not receive any value.

*''pin'' '''valueIfAbsent''':''alternativeValue'' Returns the value of a pin or the value from alternativeValue if the pin did not receive any value.

*''pin'' '''valueIfPresent''' Returns the value of a pin or nil if the pin did not receive any value.

*''pin'' '''isConnected''' Returns true if the pin has a connection
 

==== Output Pins (Bridged Smalltalk) ====

*''pin'' '''value''':''someValue'' Writes the value to the pin. Only simple object can be transferred by value (nil, booleans, integers, floats, strings). Anything else should be passed by reference (see makeRef below).
 

==== Transcript, Stderr and Stdout (Bridged Smalltalk) ====

The expecco "<code>Transcript</code>", "<code>Stderr</code>" and "<code>Stdout</code>" are also accessible from remote Smalltalk images.
However, only a limited subset of messages is supported:

*'''cr''' () Adds a linebreak (i.e. followup text will be shown on the next line)

*'''show''':''arg'' Adds a textual representation of the argument, which can be a string, number or any other object.

*'''showCR''':''arg'' A combination of show(), followed by a linebreak.

*'''nextPutAll''':''string'' String writing

*'''nextPutLine''':''string'' String printing with cr

In addition, stdout and stderr are also forwarded to the expecco Transcript window, depending on the settings in expecco ("''Extras''" → "''Settings''" → "''Execution''" → "''Tracing''" → "''Show Stdout and Stderr on Transcript''").
 

==== Passing Objects by Reference (Bridged Smalltalk) ====
By default, objects written to output pins via "'''value:'''" will be marshalled to JSON, transferred to expecco and decoded there.
Effectively, a copy of the object is created, which looses its identity when sent back later to the remote smalltalk in another action.
This would make it impossible to get handles from a remote action, which is to be sent to another action on the same remote machine.
The "makeRef" method solves this.

*''self'' '''makeRef''':''object'' creates a reference object, which can be written to a pin.

*''self'' '''makeRef''':''object'' '''name''':''aString'' ditto, but gives it a user friendly name (eg. for the expecco log)

I.e. to write a reference to a pin, use:
''somePin'' '''value''':(self '''makeRef''':''someObject'')

=== Additional Information on Bridged VisualWorks Smalltalk Actions ===

Inside bridged VisualWorks actions, the above described "Transcript" refers to the expecco Transcript; not the VisualWorks Transcript (the remote code is compiled inside an environment, where the Transcript variable has been redefined).

To send output to the VisualWorks Transcript, use "Smalltalk.Core.Transcript", as in:
...
Smalltalk.Core.Transcript show:'Hello on VW Transcript'; cr
...
Transcript show:'Hello on expecco Transcript'; cr
...
Be aware, that the VW Transcript does not understand the "showCR:" message; you need "show:" followed by "cr".

== Bridged Ruby Elementary Blocks ==

Note: This is a preliminary API documentation.
Bridged Ruby elementary actions are still being developed and the API may change slightly until officially released.

Bridged Ruby actions will execute in a Ruby interpreter.

The API looks similar to the API of regular actions, which execute inside expecco itself or another language interpreter.
However, due to Ruby language specifics, some differences are noticable.

==== Variables (Bridged Ruby) ====

The following variables are in the scope of the executed code (notice the "$" prefix; Ruby requires global variables to be prefixed by a "$" character):

*<code>$Transcript</code> a proxy which supports a few functions to display messages in the expecco Transcript window (see below)
*<code> $Stdout </code> a proxy which supports a few functions to display messages on expecco's stdout stream (see below)
*<code> $Stderr </code> a proxy which supports a few functions to display messages on expecco's stderr stream (see below)

*<code> $Dialog</code> a proxy which supports a few functions to display confirmation dialogs (see below)
 

==== Reporting (Bridged Ruby) ====

*'''error'''(''infoString'' [ ,''arg1'' ... ,''arg4'' ]) Report a defect (in the test). Up to 4 optional args are sliced into the string, if it contains "%i" placeholders. Stops execution.

*'''fail'''(''infoString'' [ ,''arg1'' ... ,''arg4'' ]) Report a failure (in the SUT). Stops execution.

*'''inconclusive'''(''infoString'' [ ,''arg1'' ... ,''arg4'' ]) Report an inconclusive test. Stops execution.

*'''activitySuccess'''(''infoString'' [ ,''arg1'' ... ,''arg4'' ]) Finishes the current activity with success (same as "success()").

*'''pass'''(''infoString'' [ ,''arg1'' ... ,''arg4'' ]) Finishes the current testCase with success.
 

==== $Transcript, $Stderr and $Stdout (Bridged Ruby) ====

The expecco "<code>Transcript</code>", "<code>Stderr</code>" and "<code>Stdout</code>" are also accessible from Ruby actions (with a $-prefix).
Notice, that $Stderr refers to expecco's stderr and $Stdout refers to expecco's stdout. Both may be (and usually are) different from the Ruby interpreter's STDERR/STDOUT.

*'''cr''' () Adds a linebreak (i.e. followup text will be shown on the next line)

*'''show'''(''arg'') Adds a textual representation of the argument, which can be a string, number or any other object.

*'''showCR'''(''arg'') A combination of show(), followed by a linebreak.

*'''nextPutAll'''(''string'') String writing

*'''nextPutLine'''(''string'') String printing with cr

*'''puts'''(''string'') String printing with cr

In addition, stdout and stderr are also forwarded to the expecco Transcript window, depending on the settings in expecco ("''Extras''" → "''Settings''" → "''Execution''" → "''Tracing''" → "''Show Stdout and Stderr on Transcript''").

 

==== $Dialog (Bridged Ruby) ====

*'''confirm'''(''msg'') Opens a simple yes/no dialog; returns a boolean.

*'''request'''(''msg'') Opens a simple string-input dialog; returns a string or nil if cancel was pressed.

*'''requestPassword'''(''msg'') same, but the entered string is not shown on the screen

*'''requestFilename'''(''msg'') asks for a filename
 

==== Logging (Bridged Ruby) ====

*'''logFail'''(''messageString'') Adds a fail message to the activity log.

*'''logError'''(''messageString'') Adds a error message to the activity log.

*'''logWarning'''(''messageString'') Adds a warning to the activity log.

*'''logInfo'''(''messageString'') Adds an info message to the activity log.

*'''alert'''(''messageString'') Adds a warning message to the activity log, and also shows a DialogBox, which has to be confirmed by the operator. The dialog box and confirmation can be disabled by a settings flag in the "''Execution''" → "''Log Settings''" dialog (by default it is disabled).

*'''warn'''(''messageString'') Same as ''alert:'' (for JavaScript compatibility).
 
==== Environment Access (Bridged Ruby) ====
*'''environmentAt'''(<varName>); Fetches and returns a value from the expecco environment which is in scope of the current activity. You can only read simple objects (numbers, booleans and strings) from ruby actions.

*'''environmentAtPut'''(<varName>, <newValue>); Writes a value into the expecco environment which is in scope of the current activity. The variable must be writable. You can only write simple objects (numbers, booleans and strings) from ruby actions.

 

==== Input Pins (Bridged Ruby) ====

*''pin''.'''hasValue'''() Returns true if the pin has received a value

*''pin''.'''value'''() Returns the value of the pin. Raises an error if the pin did not receive any value.

*''pin''.'''valueIfAbsent'''(''alternativeValue'') Returns the value of a pin or the value from alternativeValue if the pin did not receive any value.

*''pin''.'''valueIfPresent'''() Returns the value of a pin or nil if the pin did not receive any value.

*''pin''.'''isConnected'''() Returns true if the pin has a connection
 

==== Output Pins (Bridged Ruby) ====

*''pin''.'''value'''(''someValue'') Writes the value to the pin. Only simple object can be transferred by value (nil, booleans, integers, floats, strings). Anything else should be passed by reference (see <code>makeRef</code> below).
 

==== Passing Objects by Reference (Bridged Ruby) ====
By default, objects written to output pins via "'''value:'''" will be marshalled to JSON, transferred to expecco and decoded there.
Effectively, a copy of the object is created, which looses its identity when sent back later to the remote ruby in another action.
This would make it impossible to get a handle from a remote action, which is to be sent to another action on the same remote machine.
The "<code>makeRef</code>" method solves this, by creating a "pointer" or "handle" to the object inside the remote machine.

*'''makeRef'''(''object'') creates a reference object, which can be written to a pin.

*'''makeRef'''(''object'', '''name''') ditto, but gives it a user friendly name (eg. for the expecco log)
:I.e. to write a reference to a pin, use:
::: ''somePin''.'''value'''('''makeRef'''(''someObject''))

== Bridged Dart Elementary Blocks ==
coming with one of the next expecco versions
== Bridged Scheme Elementary Blocks ==
coming with one of the next expecco versions

== DotNET Elementary Blocks ==

Editing support for C# will be provided in a later expecco version. Currently, .NET objects must be instantiated and methods be called via the transparent message forwarning mechanism provided by Smalltalk. This means, that you use Smalltalk code to send (Smalltalk-) messages to proxy objects, which forward the call information to the corresponding bridge object.

As an alternative, you can use bridged IronPython actions and refer to the assembly from there.

== VisualBasic Elementary Blocks ==

Support for VisualBasic Script elementary block execution is provided as an extension plugin, and requires a separate plugin license.
It is only available for expecco running on the MS Windows operating system.

Code written as a VisualBasic elementary block is not executed directly by expecco. Instead, the code is forwarded to a VisualBasic scripting host which runs as another process either on the local or on a remote host. The scripting host must be a Microsoft Windows host (but expecco itself may run on any type of operating system). By using VisualBasic blocks, expecco's basic black box test functionality can be easily extended by many powerful gray- and white-box tests. Many libraries for device and equipment control, COM/DCOM and other technologies and UI interaction are possible with the VisualBasic plugin.

Please consult the separate [[VBScript/en | VisualBasic plugin documentation]] for more detail.

== Shell, Batch and other Script Elementary Blocks ==
There is no special API for those, except for pin-value expansion and stdin/stdout/stderr handling.
All of this is described in the [[ElementaryBlock_Element/en#Script_Action_Blocks | "Script Action Blocks" documentation]]

== Remote expecco Elementary Blocks ==

These run on a remote expecco system, and can be used to generate load (stress) or perform additional measurements.
Remote expecco actions will be available in or after the 24.2 expecco version.

--- to be documented ---

== Tutorial: Common Tasks ==

This chapter gives code fragments and examples for common tasks.

The underlying Smalltalk class library contains (among others) very powerful and robust collection, stream and number representation systems, of which many functions are useful for elementary block developers. The set of usable functions is much larger than for example in Java or C standard libraries. Thus for a newcomer to Smalltalk, it is highly recommended and fruitful to read the introduction texts and/or use the class browser for a deeper understanding. You can benefit from existing code and save a lot of development time in knowing a little about your class libraries.

Also, it is a good idea to try the sample code in a "workspace" window or within the code editor,
by selecting the piece of code to be tried, and performing the "''printIt''" menu function.
Thus you can quickly test&try code fragments without a need for an elementary block and its setup.

Or use the [[How_to_Program/en#MethodFinder:_Find_Functions_by_Example|MethodFinder]] tool to find operations.

=== String Handling ===

Notice, that in Smalltalk all collection indices are 1-based. I.e. the index of the first element is 1, and the last index is the collection's size. This is the same in Mathematica, but different in C, JavaScript, Java and others.
Thus Smalltalk loops over collection elements should run from 1 to the collection's size, not from zero to the size minus 1. You will get an index exception, if you try.

Also notice, that index-based enumerations (i.e. loops from 1 to the size) are actually seldom needed, due to the powerful "<code>do:</code>", "<code>collect:</code>", "<code>select:</code>" etc. family of enumeration methods.
These do all the index computations for you, and are often heavily tuned for better performance.

Also notice, that in Smalltalk, String is a subclass of Collection, and most of the functions described below are actually not implemented in the String class, but inherited from a superclass. Take this into consideration, when searching for String utility functions in the class browser (i.e. look there first or click on the "See Inherited Methods" button in the class browser [[Datei:SeeInheritedInBrowser.png]] ).
On the other hand, the fact that most of those functions are implemented in the Collection superclass also means, that they work on many other collections (Arrays, ByteArray, OrderedCollection, Set, Dictionary etc.).

If you are in doubt, open a [[Tools_Notepad/en|Workspace]] window, enter a piece of code and evaluate it (using the "''printIt''" menu function).
Or open the [[How_to_Program/en#Find_Functions_by_Example|Method Finder]] to find an operation given the desired outcome.

==== Copying Parts of a String ====

To extract a substring, and the index and/or count is known, use one of:

''aString'' copyFrom: ''startIndex'' to: ''stopIndex''

''aString'' copyFrom: ''startIndex''

''aString'' copyTo: ''stopIndex''

''aString'' copyFrom: ''startIndex'' count: ''n''

''aString'' copyFirst: ''count'' "/ same as copyTo:

''aString'' copyLast: ''count'' "/ gives the last count characters

''aString'' copyFrom: ''startIndex'' butLast: ''count'' "/ copy except the last count characters

All of the above will copy including the character at the start- and stop index.
I.e.
'hello world' copyFrom:2 to:5
will return 'ello'.
 [[Datei:point_right.png|20px]]This is different from some C/Java functions, which usually expect the stopIndex to be one-after the last copied element.
===== Search & Copy =====
to search for a character and copy up to that character's position, use:
''aString'' copyUpTo: ''characterToSearch''

''aString'' copyFrom:''startIndex'' upTo: ''characterToSearch''

You can also search backward from the end (i.e. the last occurrence of a character):
''aString'' copyUpToLast: ''characterToSearch''

==== Finding Elements and Substrings ====

To search for elements of a string (which are characters), use:

''aString'' indexOf: ''aCharacter''
''aString'' indexOf: ''aCharacter'' startingAt: ''startIndex''

and:

''aString'' lastIndexOf: ''aCharacter''
''aString'' lastIndexOf: ''aCharacter'' startingAt: ''startIndex''

to search backward from the end.

 [[Datei:point_right.png|20px]]The Smalltalk methods return a 1-based index, and 0 (zero) if not found; JavaScript methods return a 0-based index and -1 if not found.

[[Datei:point_right.png|20px]]Notice that a character constant is written in Smalltalk as <code>$<x></code>, where <x> is a printable character or a space. Non-printable characters must be specified by their name ("<code>Character return</code>", "<code>Character lf</code>", "<code>Character tab</code>") or their Unicode-point (decimal: "<code>Character value: 127</code>" or hex: "<code>Character value: 16r1F00</code>").

If there are multiple characters to be searched for, pass a collection of searched characters to one of:

''aString'' indexOfAny: ''aBunchOfCharacters''
''aString'' indexOfAny: ''aBunchOfCharacters'' startingAt: ''startIndex''

for example,

'hello world' indexOfAny: 'eiou' startingAt:3

looks for the next vocal at or after position 3.

Both receiver and argument may actually be any kind of Collection;
thus:
''aString'' indexOfAny: #( $a $A $e $E )

works the same.

Finally, there is a very generic search function, where you can pass a test-procedure as argument:

''aString'' findFirst:[:ch | ...a boolean test on ''ch'' ...]

will return the index of the next character for which your boolean check computes a true value.
For example, to search for the next digit, use:
''aString'' findFirst:[:ch | ch isDigit]

to search for a digit OR period OR dollar character, you can use one of:

''aString'' findFirst:[:ch | ch isDigit or:[ ch == $. or:[ ch == $$]]]
''aString'' indexOfAny:'0123456789$.'

use whichever you find more readable.
(there is also a "<code>findFirst:startingAt:</code>", and corresponding "<code>findLast:</code>" and "<code>findLast:startingAt:</code>" for backward searches)

Because it is a common task to search for separators and other non-printable characters,
special methods exist for those:

''aString'' indexOfSeparatorStartingAt: ''startIndex''
''aString'' indexOfNonSeparatorStartingAt: ''startIndex''
''aString'' indexOfControlCharacterStartingAt: ''startIndex''

where separators are the whitespace characters (space, tab, vt, cr and lf),
and control characters are all characters below ASCII 32.

All of the index-search methods return a 0 (zero) if the character is not found.

Substrings can be searched with:

''aString'' indexOfString: ''anotherString''
''aString'' indexOfString: ''anotherString'' startingAt: ''startIndex''
''aString'' indexOfString: ''anotherString'' caseSensitive: false
''aString'' indexOfString: ''anotherString'' startingAt: ''startIndex'' caseSensitive: false

''aString'' indexOfString: anotherString startingAt: startIndex

''aString'' indexOfSubCollection: ''anotherString''
''aString'' indexOfSubCollection: ''anotherString'' startingAt: ''startIndex''

There are also corresponding backward search variants "<code>lastIndexOfSubCollection:</code>".

Notice the somewhat generic names "<code>indexOfSubCollection:</code>" instead of a more intuitive "<code>indexOfString:</code>".
The reason is that these methods are inherited from collection, which does not care if the elements are
characters or other objects (<code>indexOfString:</code> is an alias for <code>indexOfSubCollection:</code>).

This means, that you can use the same method to search for a slice in an array:

#(1 2 3 4 5 6 7 8 9 8 7 6 5 1 2 3 2 1) indexOfSubCollection:#(9 8 7)

using the same code.

To find all such methods in the class browser, search for implementors of "<code>*indexOf*</code>", and look at the matches in <code>Collection</code>, <code>SequenceableCollection</code>, <code>CharacterArray</code> and <code>String</code>.

==== If you don't need the Index ====

If you only need to check if a character or substring is present, but not its position,
you can use "<code>includes:</code>", "<code>includesString:</code>", "<code>includesString:caseSensitive:</code>", "<code>includesSubCollection:</code>", "<code>includesAny:</code>" or "<code>includesAll:</code>" in a similar spirit.
These may be slightly faster and make the code more readable. They return a boolean.

==== Caseless Searches ====

For strings, special substring searches are available, which ignore case (upper/lower) differences:

''aString'' includesString: ''anotherString'' caseSensitive: false
''aString'' indexOfString: ''anotherString'' caseSensitive: false

==== Prefix and Suffix Checks ====

''aString'' startsWith: ''anotherString''
''aString'' endsWith: ''anotherString''

are obvious.
The powerful:

''aString'' startsWithAnyOf: ''aCollectionOfStrings''

searches for multiple string prefixes. For example,

'hello' startsWithAnyOf: #( 'ab' 'ce' 'de' )

would look for all of them and return false in this concrete example.
Of course, there is a corresponding "<code>endsWithAnyOf:</code>".

==== Splitting Parts of a String (or Collection) ====

The simplest are:

''aString'' asCollectionOfWords

''aString'' asCollectionOfLines

which split at separators and line-ends respectively and return a collection as they say in their name.

More generic is:

''aString'' js_split: charOrString

which returns a collection of substrings split at "''charOrString''" elements. as the name suggests, you can pass either a single character or a substring as argument.
Thus:

'hello world isn't this nice' js_split:(Character space)

will give you the strings <code>('hello' 'world' 'isnt' 'this' 'nice')</code>.
Whereas:
'some : string : separated : by : space : colon space' js_split:' : '
will return a collection containing: <code>('some' 'string' 'separated' 'by' 'space' 'colon' 'space')</code>.

Notice, that we used "<code>js_split:</code>" in the above examples, which is the method used by JavaScript's "<code>split()</code>" function. This is because in Smalltalk, the "<code>split:</code>" method has a different semantics: the receiver is a "''splitter''", and the argument is splitted by it.
 In Smalltalk, the splitter can be both a simple string or a [[Regex Pattern Info| regular expression]]. For example:

'[a-z]*' asRegex split:'123abc456def789'

will generate the collection: <code>#('123' '456' '789')</code>.

To split into same-sized pieces, use:

''aString'' splitForSize: ''charCount''

this may be less of interest for strings, but is handy to split fixed records of binary data (remember: these functions are implemented in a superclass of <code>String</code>, from which <code>ByteArray</code> also inherits).

==== Joining and Concatenating Strings ====

The simplest of them is the "," (comma) operator. This takes two collections (and as such also Strings) and creates a new collection containing the concatenation of them.
Thus:

'hello' , 'world'

will create a new string containing 'helloworld',
and:
'hello' , ' ' , 'world'

will give you 'hello world',
 and:
#(1 2 3) , #(4 5 6)
will generate a 6-element array containing the elements 1 to 6.

Notice that concatenation may become somewhat inefficient, if many strings are concatenated,
because many temporary string objects are created. Its time complexity is O(n2), where n is the number of strings concatenated.

If you have to construct a string from many substrings, either use one of the join functions below (with O(n) complexity),
or a writeStream with O(n log n) complexity.
Both handle the reallocations much more efficiently (actually: avoiding most of them).

To join a set of strings, use:

''asCollectionOfStrings'' asStringWith: ''separator''

where separator may be a character, a separator string or nil.
For example:
#( 'a' 'b' 'c') asStringWith:nil
gives 'abc',
and:
#( 'a' 'b' 'c') asStringWith:' : '
returns: 'a : b : c'

Using a writeStream, write:

|w result|

w := WriteStream on:(String new:10).
w nextPutAll: 'a'.
w nextPutAll: 'b'.
...
result := w contents

or, using a convenient utility method (which does exactly the same):

result := String streamContents:[:s |
s nextPutAll: 'hello'.
s nextPutAll: 'world'.
...
s nextPutAll: 'Nice world'
].

but please read more on streams in the stream chapter below.

==== Formatting Strings (Method A) ====

For text messages, you may want to construct a pretty user readable string which contains printed representations of other objects.
For this, use:
''formatString'' bindWith: ''argument''

''formatString'' bindWith: ''argument1'' with: ''argument2''

''formatString'' bindWith: ''argument1'' with: ... with: ''argumentN'' (up to 5 arguments)

''formatString'' bindWithArguments: ''argumentCollection'' (any number of arguments)

using the "<code>{ .. }</code>" array constructor (notice the periods as expression separators), this is usually written as:

''formatString'' bindWithArguments: { ''argument1'' . ''argument2'' . ... . ''argumentN'' }

The formatString itself may contain "%X" placeholders, which are replaced by corresponding
printed representations of the argumentX. The arguments will be converted to strings if they are not, thus arbitrary objects can be given as argument (although, in practice, these are usually numbers).

If many arguments are to be passed in,
the placeholder names X may consist of a single digit (1-9) only for the first 9 arguments.
For other arguments, you must write "%(X)". I.e. '%(10)' to get the tenth argument sliced at that position (1).

The last of the above methods is a powerful tool, in that it does not only handle argumentCollections indexed by numbers (i.e. Array of arguments), but also Dictionaries, which are indexed by name.

For example, if you have a Dictionary collection of a person record (in expecco: a compound datatype instance), with element keys "firstName", "lastName" and "city",
you can generate a nice printed string with:

|record|

record := Dictionary new. "/ example using a dictionary
record at:'firstName' put: 'Fritz'.
record at:'lastName' put: 'Müller'.
record at:'city' put: 'Stuttgart'.

'%(lastName), %(firstName) lives in %(city)' bindWithArguments: record.

gives you the string: 'Müller, Fritz lives in Stuttgart'.
 In combination with a expecco compound datatype instance, this would be:

|person|

person := myType new.
person firstName:'Fritz'.
person lastName:'Müller'.
person city:'Stuttgart'.

'%(lastName), %(firstName) lives in %(city)' bindWithArguments: person.

1) Note: this has been relaxed in 19.2, where %10 is allowed. However, all digits up to the first non-digit character will make up the index. If you need a sliced in value followed by a digit, you'd still have to use %(x).

==== Formatting Strings with Printf (Method B) ====
There is also a formatting method similar to "<code>printf</code>". It takes a format string and a number of arguments and constructs a string representation.
As Smalltalk does not support variable numbers of arguments, these must be passed with different keyword messages:

''formatString'' printfWith:''arg''

''formatString'' printfWith:''arg1'' with:''arg2''

''formatString'' printfWith:''arg1'' with:''arg2'' with:''arg3''
... up to 5 arguments

''formatString'' printf:''argVector''

For the argVector, use the "{" .. "}" construct.

For example,

'%05d 0x%-7x %f' printf:{ 123 . 517 . 1.234 }
generates the string:
'00123 0x205 1.234'

The above provides the functionality of C's "sprintf" - i.e. it generates a string as result. However, streams also understand printf-messages, so you can also print directly to a stream:

Transcript printf:'%05x\n' with:12345
or:
Transcript printf:'%05x %d %f %o\n' withAll:{ 123. 234*5. 1.234. 254 }

Notice, that printf translates the standard C-character escapes "\n", ”\t" etc.

==== Formatting Strings with Embedded Expressions (Method C) ====
A string constant prefixed with "e" is a so called expression-string. This may contain Smalltalk expressions enclosed in "{" .. "}", which are sliced into the string (actually, the expression's printString is sliced in). In addition, C-style escape sequences like "\n" are recognized in e-strings.

Transcript show: e'today is {Date today} and the time is {Time now}\nAnd the dayName is {Date today dayName}'.

==== Regex and Glob Matching ====

Both match a string against a match pattern, but the syntax and functionality is different.
* Glob is much easier to use but less powerful. Glob is the match algorithm used in the Unix and MS-DOS filesystem (e.g. when saying "<code>ls *.foo</code>" or "<code>dir *.foo</code>" on the command line).
* [[Regex Pattern Info| Regex]] is the algorithm used in tools like "grep" and many text processing systems and languages.

Notice that regex patterns are different and not just a superset of glob patterns. Especially the meanings of "*" and "." are different.
 
Please consult Wikipedia for more information on Regex [https://en.wikipedia.org/wiki/Regular_expression] and GLOB [https://en.wikipedia.org/wiki/Glob_%28programming%29].
A chapter on regex is also found in this [[Regex Pattern Info| wiki]].

For a Glob match, use:

''aGlobPattern'' match:''aString''

''aGlobPattern'' match:''aString'' caseSensitive:false

or, reversed argument order, if you prefer:
''aString'' matches:''aGlobPattern''

''aString'' matches:''aGlobPattern'' caseSensitive:false

For a regex match, use:

''aString'' matchesRegex:''aRegexPattern''

''aString'' matchesRegex:''aRegexPattern'' caseSensitive:false

''aString'' matchesRegex:''aRegexPattern'' ignoringCase:true "/ an alias to the above

Sorry for the inconsistent method naming which is due to the fact that the regex matcher originated in a public domain package, which was developed independently from the original ST/X system. In order to remain compatible with other Smalltalk dialects, the names were kept.

The CharacterArray class provides a whole bunch of useful match methods (eg. to extract multiple occurrences of a pattern, to do prefix matches and to extract sub patterns from a complex match pattern). Please use the class browser (from the "''Extras''" → "''Tools''" menu) to find them.

==== Code Converting ====

There are code converters for various character encodings in and below the CharacterEncoder class.
Most of them are obsolete or seldom used these days, as now most systems support Unicode (which was not the case, the ST/X was written 30 years ago and switched to Unicode in the 90's!).

In general, you can get an instance of an encoder via a convenient CharacterEncoder interface:

CharacterEncoder encoderFor:<encoding>

or:

CharacterEncoder encoderToEncodeFrom:<encoding1> to:<encoding2>

where encoding is a name, such as 'iso8859-1', 'unicode', 'utf8', 'utf16', 'ascii', 'jis7' etc.

Thus, to encode a string from Unicode (which is the internal encoding anyway) to Japanese JIS0201, use:

(CharacterEncoder encoderFor:#'jis0201') encode:'hello'

or to encode from Microsoft cp1253 to koi8-r, use:

(CharacterEncoder encoderToEncodeFrom:#'cp1253' to:#'koi8-r') encode:<''someStringInCP1253''>

You will probably not need that general interface, but use UTF-8 these days.
For those, the String class provides easier to use interface:

''aString'' utf8Encoded

''aString'' utf8Decoded

==== Collection Slices ====

A slice is a reference to a subcollection, which looks and behaves like any other collection, but shares the underlying data with the original collection. Thus modifications in either the original or slice are visible in the other and vice versa.

To get a slice, use one of the "<code>from:</code>", "<code>from:to:</code>", "<code>to:</code>" and "<code>from:count:</code>" methods (the names are similar to the above mentioned "copy*" methods).

For example:

data := ... some big ByteArray read from a file ...

record1 := data from:1 to:recordSize.
record2 := data from:(recordSize+1) to:recordSize*2.
etc.

gives you the records from the big collection as individual objects. If any modification is made to any of the slices, that modification is actually made in the underlying data collection (i.e. C-Programmers may think of this as a "''pointer into the data object''").

Slices are especially useful with bulk data processing, to avoid the creation of individual record copies.

However, they are a bit dangerous, as the programmer has to be always aware of possible side effects. If you are uncertain, do not pass a slice to another (unknown) function; instead use the corresponding copy methods.

=== Stream Handling ===

Streams can be both internal streams (streaming out-of or into a collection) or external streams.
External streams are always byte- or character-oriented and operate on files, sockets, pipes or i/o devices.
An internal stream's element type depends on the underlying collection.

The following presents only a very small excerpt of the full stream protocol.
Please refer to the online documentation of the Smalltalk/X stream classes.

==== Creating (Internal Streams) ====

streams for reading:
rs := ReadStream on:''aCollection''.

rs := ''aCollection'' readStream

streams for writing:
ws := WriteStream on:(String new:''initialSize'')

ws := '' writeStream

ws := WriteStream on:(Array new)

notice that the underlying collection is reallocated when more elements are added due to nextPut: operations.
The reallocations are done by doubling the size, resulting in O(n log n) complexity. If you have a rough idea on the final size, preallocating with an initialSize avoids or reduces the number of reallocations.

==== Checking ====

''s'' atEnd
returns true iff the read stream "s" is positioned at the end.
''s'' size
returns the size of the read stream's buffer, or the number of elements written into a write stream.

==== Positioning ====

''s'' position

returns the stream's current read position, starting at 0 when at the beginning.
I.e. position represents the number of elements which have already been read or written.

''s'' position:''pos''

set the position.

''s'' rewind

reset the position to the beginning

''s'' setToEnd

set the position to the end (normally only useful for appending write streams)

''s'' backStep

position one element backwards

''s'' skip:n

skip n elements when reading

==== Reading ====

''rs'' next

retrieve the next element from the stream. Nil if there are no more elements.

''rs'' next:''count''

retrieve the next "n" elements from the stream.

''rs'' nextAvailable:''count''

retrieve the next "n" elements or whatever number of elements are available.

''rs'' upTo:''element''

retrieve elements up to an element which is equal to "element"

''rs'' skipTo:''element''

skip over elements up to an element which is equal to "element"

''rs'' through:''element''

retrieve elements up-to and including an element which is equal to "element"

==== Writing ====

''ws'' nextPut:''element''

append element to the stream.

''ws'' next:''count'' put:''element''

append element multiple times to the stream.

''ws'' nextPutAll:''aCollectionOfElements''

append all elements from the given collection to the stream.

''ws'' println

append a newline character.

''ws'' cr

also

''ws'' nextPutLine:''aCollectionOfElements''

append all elements from the given collection followed by a newline to the stream.

''ws'' print:''anObject''

append a printed representation of anObject (for humans) to the stream.

''ws'' store:''anObject''

append the printed representation of anObject (for the system) to the stream.
Unless the object has recursive references, a copy of the element can be reconstructed with <code>Object readFrom:</code>''aReadStream''

''ws'' println:''anObject''

append a printed representation of anObject (for humans) to the stream, followed by a newline.

''ws'' printCR:''anObject''

the same

''ws'' contents

retrieve the stream's contents (typically, the characters buffered so far)

==== File Streams ====

''aString'' asFilename readStream

''aString'' asFilename writeStream

See more below in the chapter on [[#File_Operations |file operations]].

=== Numbers ===

==== Reading Numbers from a String ====

To read a number from a string, use the "readFrom:" method provided by the number classes,
where the argument is either a string, or a headstream.
A readstream is obtained with either "<code>(ReadStream on:''aString'')</code>" or the more convenient "<code>(''aString'' readStream)</code>".

Thus, in general, code to read a number looks like:
<class> '''readFrom:''' ''aString''
or:
<class> '''readFrom:''' (ReadStream on:''aString'')
or:
<class> '''readFrom:''' (''aString'' readStream)

where "<class>" is one of "<code>Integer</code>", "<code>Float</code>", "<code>FixedPoint</code>" or "<code>Number</code>".
If "<class>" is "<code>Number</code>", any type of number will be read and returned. Otherwise, only that type of number will be accepted (i.e. "<code>Integer readFrom:''String''</code>", will report an error if there is a decimal point in the string.

If the string contains nothing but the number string, the above two code expressions behave the same.
However, there is an often overlooked difference in case of extra characters after the number:

* the string-reader expects that the given string contains a representation of a corresponding number object, and NO extra characters before or after it. It will report an error otherwise.

* in contrast, the stream reader will first skip any spaces, then read as many characters as required from the stream, return the number and leave the stream positioned after the number. It will report an error if no number can be read. More values can be read from the stream if required.

Thus both:
Integer '''readFrom:''' '1234'
and:
Integer '''readFrom:''' (ReadStream on:'1234').

return the Integer object 1234.

Whereas:
Integer '''readFrom:''' '1234bla'
will raise an error, but:
myStream := ReadStream '''on:''' '1234bla'.
Integer '''readFrom:''' myStream.

returns the integer 1234 and leave the stream positioned on the 'bla'. Thus further elements can be read from the stream later.

Notice that "<code>Integer readFrom:</code>" will read an integer, but not a float.
Thus:
Integer '''readFrom:''' '1234.5'
will raise an error, but:
Integer '''readFrom:''' (ReadStream on:'1234.5').

will return the Integer object 1234 and leave the stream positioned on the decimal point character.

When expecting an arbitrary number (e.g. with or without decimal point),
use:
Number '''readFrom:''' ''aStringOrStream''
which will return either an integer object or a float object depending on what it gets.

If you want to enforce getting a float, use
Float '''readFrom:''' ''aStringOrStream''
which returns the float "1234.0", even when given the string "1234".

===== Error handling =====

By default, the readers raise an exception, if any conversion error occurs.
This can be caught in an error handler as described elsewhere (hint: catch the error with "<code>on:do:</code>").

However, the conversion routines can also be given a correction function as argument,
which is invoked in case of an error, and which provides a replacement value. This is easier and shorter to write then an exception handler.

For this, all of the methods described are also present in a variant with an extra "<code>onError:</code>" argument, which provides that replacement.

For example:

Integer '''readFrom:''' ''aString'' '''onError:''' [ 0 ]

will return the number as usual if OK, but zero if not.
 Of course, arbitrary code can be provided inside this handler - especially it may show an error dialog and ask the user for a replacement, or return from the executed elementary block:

val := Integer
'''readFrom:'''aString
'''onError:'''[
|ersatz|
ersatz := Dialog '''request:''''Please enter a correct number'.
Integer '''readFrom:'''ersatz
]

===== Reading with a Different Decimal Point Character =====

If the number was originally for a european, it may contain a decimal point different from "." -
for example, in Germany you may encouter a monetary amount as "1245,99".

For this, use:

Float '''readFrom:''' ''aStringOrStream'' '''decimalPointCharacters:''' ','

or (better):

FixedPoint '''readFrom:''' ''aStringOrStream'' '''decimalPointCharacters:''' ','

If your code has to deal with both US and German numbers, provide all possible decimal points in the string, as in:

FixedPoint '''readFrom:''' ''aStringOrStream'' '''decimalPointCharacters:''' ',.'

===== Reading Multiple Numbers from a Stream =====

A common task is to read multiple numbers from a single long string.
Of course, you could first split the string into pieces and use the above "readFrom:" on each.

This may also be a quick&dirty solution, if the individual number strings are contained in fixed-length fields and there are no separators in between the fields (but read below for a better way to do this).
Take a look at the string handling examples on how to split strings.

To read multiple numbers, the best solution is to first create a read stream on the string, then read the individual numbers:

myString := '1234 456.7 0.5 2345.3456 3234234234234234234234234234234234234'.
myStream := myString '''readStream'''.

n1 := Number '''readFrom:''' myStream. "/ gives the integer 1234 in n1
n2 := Number '''readFrom:''' myStream. "/ gives the float 456.7 in n2
n3 := Number '''readFrom:''' myStream. "/ gives the float 0.5 in n3
n4 := FixedPoint '''readFrom:''' myStream. "/ gives the fixedPoint 2345.3456 in n4
n5 := Number '''readFrom:''' myStream. "/ gives the large integer 3234...34 in n5

Notice that "<code>readFrom:</code>" first skips any separators (spaces) - therefore no extra code is needed to deal with those.

If extra stuff needs to be skipped, use any of the existing stream functions (<code>skipFor:</code>/<code>skipUntil:</code> etc.). If none does the job, you can look at individual characters and skip until a match is found.
For example, to read 3 numbers from the following string '123 bla 456.8|0.5',
you could use:

s := '123 bla 456.8|0.5' readStream.
n1 := Integer '''readFrom:'''s.
s '''skipSeparators'''.
s '''nextAlphanumericWord'''. "/ skips over the 'bla'
n2 := Number '''readFrom:'''s.
s next. "/ skips over one character
n3 := Number '''readFrom:'''s.

of course, the above code would not handle strings like '123 bla bla 456.8|0.5' or '123 bla 456.8 |0.5'.
 Using "peek", which looks at the next character in the stream without consuming it,
we could to change the code to:

n1 := Integer '''readFrom:'''s.
[ s '''peek''' '''isDigit''' ] '''whileFalse:'''[ s '''next''' ]. "/ skips over the 'bla bla'
n2 := Number '''readFrom:'''s.
s '''next'''. "/ skips over one character
n3 := Number '''readFrom:'''s.

Notice that "<code>peek</code>" returns nil, if the end of the stream is reached. And that "<code>nil isDigit</code>" will report an error (because only characters can be asked for being a digit).
Thus, the code like the above is not prepared to read a variable number of numbers.

===== Reading with Scanf =====

There is also a C-like scanf utility, which can read numbers, strings, characters in various formats.

myString := '1234 456.7 0.5 2345.3456 3234234234234234234234234234234234234'.
values := '%d %f %f %f %d' '''scanf:''' myString.

generates a collection of numbers in "values":
OrderedCollection(1234 456.7 0.5 2345.3456 3234234234234234234234234234234234234)

The details and format characters are described in the PrintfScanf utility class, here is a short summary:

Conversions (upper case same as lower case):
* 'b' binary (base 2)
* 'c' character or (first char of string)
* 'd' decimal
* 'e' float
* 'f' float
* 'g' float
* 'i' integer (alias for 'd')
* 'o' base-8 octal
* 's' string
* 'u' integer
* 'x' base-16 hex

Length prefix:

* 'h' with float formats: reads as ShortFloat
* 'L' with float formats: reads as LongFloat

Examples:
* '%d %x' '''scanf:''''1234 ff00' -> OrderedCollection(1234 65280)
* '%d %s' '''scanf:''''1234 ff00' -> OrderedCollection(1234 'ff00')
* '%d %x %b' '''scanf:''''1234 ff00 1001' -> OrderedCollection(1234 65280 9)

==== Reading a Particular Number of Numbers from a Stream ====

Assume that you are given a number which defines how many numbers to extract from a given string.

Of course, you can use a "<code>start to: stop do:[:idx |...</code>" loop,
but experienced Smalltalk programmers make use of the collection protocol,
as in:
(1 to: count) collect:[:idx | Number readFrom:aStream ]

Such a construct is needed e.g. when you have to parse a string, where the first entry defines how many numbers follow:

coll := (1 to: (Integer readFrom:myString)) collect:[:idx | Number readFrom:aStream ].

which would parse the string "5 1.0 3.0 2.0 -1.0 .05" into a 5-element collection containing the converted numbers.

==== Reading a Variable Number of Numbers from a Stream ====

To do so, we should collect numbers as being read from the stream in a collection:

collectedNumbers := OrderedCollection new.

[ aStream atEnd ] whileFalse:[
collectedNumbers add: ( Number readFrom:aStream ).
]

or, if any non-digits and non-spaces between numbers should be skipped,
use:

collectedNumbers := OrderedCollection new.

[ aStream atEnd ] whileFalse:[
aStream skipUntil:[:char | char isDigit].
collectedNumbers add:( Number readFrom:aStream ).
]

==== Using the Pattern Matcher to Extract Parts ====

In rare situations, complex patterns need to be matched and numeric values
retrieved from the matched parts. For this, use a regex pattern matcher to first extract parts from the string, and then convert the substrings.
For example, to fetch numbers after certain keywords in a string, you could use:

"/ assuming that the string is of the form:
"/ <..arbitrary-text...>key1<number1><...arbitrary text...>key2<number><...arbitrary text...>
"/ where arbitrary text may even contain key1 and key2, but not followed by a number,
"/ we first use a regex to match, then convert the matched regex parts:

myString := 'bla bla key1 bla key11234more bla key2 bla key29876bla bla'.

parts := myString allRegexMatches:'((key[12]))([0-9]+)'.
"/ now, parts contains #( 'key11234' 'key29876'
numbers := parts collect:[:eachPart | Number readFrom: (eachPart copyFrom:5) ].
"/ now, numbers contains #( 1234 9876 )

notice that ''parts'' delivers the matched strings i.e. the collection ('key11234' 'key29876'),
so that we have to skip over the 'keyX' prefix before extracting the numbers.

=== File Operations ===

Expecco (i.e. Smalltalk) represents file names as instances of a specialized class called "<code>Filename</code>". These look similar to strings, but provide an abstraction over details of the underlying file- and operating system.

This makes it possible to write portable code which runs on Windows, Linux and even VMS, even though these systems use very different filename separators and volume naming schemes.

Thus, we recommend to use filename operations instead of string concatenation, e.g. to construct pathnames.
In Smalltalk, the abstract class "<code>Filename</code>" is subclassed by concrete classes named "<code>PCFilename</code>" or "<code>UnixFilename</code>".
You should not access those concrete classes explicitly by name!
Instead, always refer to "<code>Filename</code>" and let Smalltalk decide, which concrete class to use.
(unless you know that you are dealing with a unix-style filename, independent of your operating system, which is e.g. the case if you deal with CVS names or you get file-URLS as strings).

for now, a short summary:

''aString'' asFilename - to get a Filename-instance for a given String instance

''aFilename'' readStream - to get a readStream on the contents of a file

''aFilename'' writeStream - to get a writeStream writing to a file

''aFilename'' appendingWriteStream - to get a writeStream appending to the end of a file

==== Checking ====

''aFilename'' exists "/ true if the file exists

''aFilename'' isReadable "/ true if it is readable

''aFilename'' isWritable

''aFilename'' isExecutable "/ for folders, this means: "can be changed into"

''aFilename'' isExecutableProgram

''aFilename'' fileSize

''aFilename'' isDirectory

''aFilename'' isNonEmptyDirectory

''aFilename'' isRegularFile

''aFilename'' isSymbolicLink

''aFilename'' info "/ gets all info; follows any symbolic link. Includes ownerID, groupID, access and modification times etc.

''aFilename'' linkInfo "/ gets all info of a symbolic link itself. Includes ownerID, groupID, access and modification times etc.

''aFilename'' accessTime

''aFilename'' modificationTime

''aFilename'' creationTime "/ (same as modificationTime on Unix systems)

''aFilename'' fileType

''aFilename'' mimeType

==== File names ====

''aFilename'' pathName

''aFilename'' directory "/ the containing directory, as a Filename instance

''aFilename'' directoryName "/ ditto, as string

''aFilename'' baseName

''aFilename'' suffix

''aFilename'' hasSuffix:''aString''

''aFilename'' isAbsolute

''aFilename'' isRelative

''aFilename'' / ''subPath'' "/ yes, "/" is an operator to construct the name of a file inside a folder

''aFilename'' construct:''subPath'' "/ alternative to "/"

==== Operations ====

''aFilename'' makeDirectory

''aFilename'' recursiveMakeDirectory "/ ensures that all folders along the path are also created.

''aFilename'' removeDirectory "/ raises an error, if the folder is not empty

''aFilename'' recursiveRemoveDirectory "/ removes everything below also

''aFilename'' moveTo:''newName''

''aFilename'' copyTo:''newName''

''aFilename'' recursiveCopyTo:''destinationName''

==== Directory Contents ====

''aFilename'' directoryContents

''aFilename'' directoryContentsDo:[:eachFile | ...]

''aFilename'' filesMatching:aGLOBPatternString

==== File Contents ====

''aFilename'' contents
retrieves the contents as a collection of line strings.
Be careful - this should not be used for huge files.

''aFilename'' contentsAsString
retrieves the contents as one (possibly big) string.
Be careful - this should not be used for huge files.

''aFilename'' binaryContentsOfEntireFile
retrieves the contents as one (possibly big) byte array.
Be careful - this should not be used for huge files.

''aFilename'' readingLinesDo:[:eachLineString | ... ]
better use this for large files. Ensures that the file is closed.

''aFilename'' readingFileDo:[:stream | ... ]
or that to read inside the code block. Ensures that the file is closed.

=== Shared Data and Synchronization ===

A number of mechanisms for synchronisation and mutual access to shared data structures are available: <code>Semaphore</code>, <code>RecursionLock</code>, <code>Monitor</code>, <code>SharedQueue</code>, <code>SharedCollection</code> and the <code>synchronized:</code> method, which is understood by every object.
For details, please refer to the Smalltalk/X Online Documentation.

== Examples ==

The following code examples contain versions for Smalltalk, JavaScript, Groovy and Node.js.
Notice that Groovy and Node.js actions are invoked via a remote procedure call ([[Glossary#RPC|RPC]]) mechanism, which means that they are much slower due to the communication, encoding, decoding and general round trip delays. Therefore, Groovy and Node.js blocks (bridged actions in general) should only be used to access data inside the system under test or to call functions which are not available in the base system (such as additional protocols or hardware access, for which only a JAR or node- or python package is available). Or, functions for which the call overhead is small compared to the runtime (i.e. for heavy computing tasks, it may very well make sense).

Thus, most of the examples below are for demonstration purposes, not for real world scenarios (i.e. it will certainly slow down your test runs, if you do math via Groovy or even Node.js, as shown below).

Also bear in mind, that the underlying numeric representations are less flexible and more error-prone if you do math outside Smalltalk:
in Groovy, because there will be no signalling of overflow/underflow situations. Especially with integer arithmetic, which may be outside the 32bit/64bit range. Also, Java has no exact fraction representations, which means that you may loose precision in floating point operations.

Things are even worse in Node.js, which represents all numbers as double precision floats, giving roughly 53 bits of precision. Thus, in Node.js the two integers 12345678901234567890 and 12345678901234567891 will be reported as being equal! (this may change in a future Node version, though).

[[Datei:point_right.png|20px]] Do NOT use Groovy or Node.js for numeric computations, if large integer values are involved (or use a Bignum package).

=== Reading/Writing Pin Values ===

Assuming that the block has two input pins, named "<code>in1</code>" and "<code>in2</code>" and two output pins, named "<code>out1</code>" and "<code>out2</code>",
all of String type,
the following blocks write concatenated strings to both outputs:

===== JavaScript =====
(runs inside expecco when executed)
execute() {
out1.value( in1.value() + in2.value() );
out2.value( in2.value() + in1.value() );
}

===== Smalltalk =====
(runs inside expecco when executed)
execute
out1 value:(in1 value , in2 value).
out2 value:(in2 value , in1 value).

===== Groovy =====
(runs inside the JVM, which may be the system under test or another machine running Java)
def execute() {
out1.value( in1.value() + in2.value() );
out2.value( in2.value() + in1.value() );
}

===== Node =====
(runs inside a node VM, which may be the system under test or another machine running "node")
function execute() {
out1.value( in1.value() + in2.value() );
out2.value( in2.value() + in1.value() );
}

===== Python =====
(runs inside a Python interpreter, which may be the system under test or another machine running "python")
def execute():
out1.value( in1.value() + in2.value() )
out2.value( in2.value() + in1.value() )

===== C =====
static void execute() {
char* s1 = stringValue(in1);
char* s2 = stringValue(in2);
char buffer[512];

snprintf(buffer, sizeof(buffer), "%s%s", s1, s2);
putString(out1, buffer);

snprintf(buffer, sizeof(buffer), "%s%s", s2, s1);
putString(out1, buffer);
}

Note: be aware, that due to the Remote Procedure Call ([[Glossary#RPC|RPC]]), the calling overhead of bridged actions is in the order of milliseconds,
whereas actions executed inside expecco (Smalltalk and JavaScript) are executed typically within a few hundred nanoseconds.

Thus, bridged actions are typically used to invoke longer running, complex operations or to trigger services, which run autonomous, or to talk to interfaces/devices. They are normally not be used for trivial operations like string manipulation or arithmetic.

=== Reading/Writing Environment Variables ===

Assuming that a String-typed environment variable named "''IncDec''" and an Integer-typed variable named "''Counter''" exist in the project's environment, and are writable,
the following blocks read and write to either variable:

===== JavaScript =====
(runs inside expecco, when executed)
execute() {
if ( environmentAt("IncDec") == "inc" ) {
environmentAt_put("Counter", environmentAt("Counter") + 1);
} else {
environmentAt_put("Counter", environmentAt("Counter") - 1);
}
}

===== Smalltalk =====
(runs inside expecco, when executed)
execute
(self environmentAt:'IncDec') = 'inc' ifTrue:[
self environmentAt:'Counter' put:(self environmentAt:'Counter')+1.
] ifFalse:[
self environmentAt:'Counter' put:(self environmentAt:'Counter')-1.
]

===== Groovy =====
(runs inside the JVM, which may be the system under test or another machine running Java).
Notice that the environment-access from inside Groovy involves even more overhead, as those require another RPC call from Groovy back to expecco. When executed, the code below will make 4 full remote-procedure call roundtrips (1 for the call and return value, one for "environmentAt(IncDec)", one for "environmentAt(Counter)" and a fourth one for "environmentAt_put()").

def execute() {
if ( environmentAt("IncDec") == "inc" ) {
environmentAt_put("Counter", environmentAt("Counter") + 1);
} else {
environmentAt_put("Counter", environmentAt("Counter") - 1);
}
}

=== Sending Messages to the Transcript ===
The <code>Transcript</code> refers to the expecco console, if it has been opened (via the "''Extras''" → "''Tools''" menu). If it is not open, "Trnscript" will refer to the standard error stream (Stderr).
In place of "Transcript", the following examples also work for "Stdout" and "Stderr".

===== JavaScript =====
(runs inside expecco, when executed)
execute() {
Transcript.showCR("---------------------");
for (var y=1; y<=10; y++) {
for (var x=1; x<=10; x++) {
Transcript.show( x * y );
Transcript.show( " " );
}
Transcript.cr();
}
}

===== Smalltalk =====
(runs inside expecco, when executed)
execute
Transcript showCR:'---------------------'.
1 to:10 do:[:y |
1 to:10 do:[:x |
Transcript show:(x * y); show:' '.
].
Transcript cr.
].

===== Groovy =====

A few of the common messages and objects for logging and printing are also made available to Groovy code. Of course, a hidden inter-process mechanism is used, which forwards those calls back to expecco (remember: the Groovy code runs inside the system under test). The <code>Transcript</code> object seen by Groovy code is such a proxy object which implements a subset of the Smalltalk Transcript object but passes the argument strings via IPC back to expecco.
So although the code looks similar to the above, the internal implementation (and timing) is completely different, because these calls are implemented as RPC calls from Groovy back to expecco.

(runs inside JavaVM when executed)
def execute() {
Transcript.showCR("---------------------");
for (int y=1; y<=10; y++) {
for (int x=1; x<=10; x++) {
Transcript.show( x * y );
Transcript.show( " " );
}
Transcript.cr();
}
}
For compatibility with existing Java/Groovy code, the functions <code>print()</code> and <code>println()</code> can also be used
(in addition to the above used <code>show()</code>, <code>showCR()</code> and <code>cr()</code> functions)

===== Node =====

A subset of the logging and printing functions are available to Node code. Of course, a hidden inter-process mechanism is used, which forwards those calls back to expecco (remember: the code runs inside the system under test). The <code>Transcript</code> object seen by Node code is such a proxy object which implements a subset of the Smalltalk Transcript object, but passes the argument strings via IPC back to expecco.

So although the code looks similar to the above, the internal implementation (and timing) is completely different, because these calls are implemented as RPC calls from Node back to expecco.

(runs inside Node when executed)
function execute() {
Transcript.showCR("---------------------");
Transcript.show( "hello " );
Transcript.show( "world" );
Transcript.cr();
Transcript.show( "A message with embedded args: %1 and %2\n", "foo", 123);
}
For compatibility with existing Node programs, you can also use "<code>console.log()</code>"
and "<code>console.error()</code>".

=== Square Root Block ===

A function, which computes the square root of its input value, could be implemented like that:
(the names of the pins are: ''in'' and ''out'', their data type is ''Number):

===== JavaScript =====
(runs inside expecco, when executed)
execute() {
var inValue;

inValue = in.value; // Reading input pin value
out.value( inValue.sqrt() ); // Writing to output pin
}
alternative:
execute() {
var inValue;

inValue = in.value; // Reading input pin value
out.value( Math.sqrt(inValue) ); // Writing to output pin
}

===== Smalltalk =====
(runs inside expecco, when executed)
execute
|inValue|

inValue := in value. "/ Reading input pin value
out value: inValue sqrt. "/ Writing to output pin

===== Groovy=====
(runs inside a JVM/the SUT, when executed). As mentioned above, this kind of operation should definitely be executed in Smalltalk/JavaScript inside expecco, and not in the system under test, due to the [[Glossary|RPC]] overheads.
def execute {
Object inValue;

inValue = inPin.value(); // Reading input pin value
outPin.value(Math.sqrt(inValue)); // Writing to output pin
}
(Notice: "in" is a reserved keyword in Groovy and cannot be used as pin name)

===== Node=====
(runs inside Node, when executed).
function execute {
outPin.value(Math.sqrt(inPin.value()));
}
(Notice: "in" is a reserved keyword in Node and cannot be used as pin name)

=== Random-Fail Block ===

A block, which randomly fails (to demonstrate exception handling), could be implemented like:

===== JavaScript =====
(runs inside expecco, when executed)
execute() {
var dice;

dice = Random.nextIntegerBetween_and_(1,6);
if (dice <= 2) {
fail();
}
}

===== Smalltalk =====
(runs inside expecco, when executed)
execute
|dice|

dice := Random nextIntegerBetween:1 and:6.
(dice <= 2) ifTrue:[
self fail.
].

===== Groovy =====
(runs inside a JVM/the SUT, when executed)
execute() {
Random rand = new Random();
int dice = rand.nextInt(5)+1;

if (dice <= 2) {
fail();
}
}

=== Calling other Actions ===

Script code can call other action blocks via the "<code>call</code>" method/function.
Notice, that the call is "''by name''" or "''by ID''", and the called function is specified by a string argument.
The following examples assume that action blocks named "''Action_A''" and "''Action_B''" are present, and that "Action_B" expects two numeric arguments and returns a value through its single output pin.

===== JavaScript =====
(runs inside expecco, when executed)
execute() {
var result;

call("Action_A");
result = call("Action_B", 123.0, 9999);
Transcript.showCR("got result: %1", result);
}
</PRE></CODE>

===== Smalltalk =====
(runs inside expecco, when executed)
execute
|result|

self call:'Action_A'.
result := self call:'Action_B' _:123.0 _:9999).
Transcript showCR:('got result: %1' bindWith:result).

===== Groovy =====
runs inside a JVM/the SUT, when executed, but the called actions are expecco actions;
i.e. the call performs a remote-procedure-call back to expecco, to execute the called action, and continue in the JVM's action when finished.
execute() {
var result;

call("Action_A");
result = call("Action_B", 123.0, 9999);
Transcript.showCR("got result: %1", result);
}

===== Node =====
runs inside the node interpreter, when executed.
The call performs a remote-procedure-call back to expecco, to execute the called action, and continue in the node action when finished.

Notice, that due to the single threaded callback oriented nature of node,
the value from the called function is passed back via a callback function,
not as return value. This is required because the "call" is actually performing
a remote procedure call into expecco (i.e. interprocess communication).
It is also currently not possible to call another node action from a node action (neither directly, nor indirectly).

function execute() {
var result;

Transcript.showCR("calling from Node...");
call("Action_A", function(err, result) {
call("Action_B", 100, 200, function(err, result) {
Transcript.showCR("got value: %1", result);
success();
});
});
}

=== Using the Smalltalk/X Class Library (Smalltalk and JavaScript Blocks Only) ===

Please note, that besides these direct interfaces with the expecco system described here, you can also use the whole class library of the runtime system. Please check the corresponding [http://live.exept.de/doc/online/english/programming/TOP.html Smalltalk/X Documentation] as well as the [http://live.exept.de/ClassDoc Documentation of the Class APIs].

expecco includes a fully featured class browser, to explore the underlying system's code.

You will see the source code, if you have checked the "''Install Source Code''" checkbox during the installation procedure (if you did not, redo the installation, and only check this box). You can also access the source code via the public eXept CVS repository.

The class browser is opened via the main-menu's "''Extras''" → "''Tools''" → "''Class Browser''" item. It is documented in full detail in the [http://live.exept.de/doc/online/english/programming/TOP.html Smalltalk/X Documentation].

Here are a few more examples, using that class library:

=== Bulk-Data Reading from a File ===

The following code reads a measurement data block of 100000 floating point values from file. The file was created beforehand by a recorder device, which was triggered by a dll-callout.
For the demonstration, the code below does not read its values from input pins. In a real world application, the size of the file and its fileName would probably be passed in via input pins, of course.

===== JavaScript =====
execute() {
var N; // should be read from an input-pin
var fileName; // should be read from an input-pin
var dataArray;
var fileStream;

N = 100000;
fileName = 'dataFile.dat';
fileStream = fileName.asFilename().readStream();
dataArray = Array.new(N);
for (i=1; i<=N; i++) {
dataArray[i] = fileStream.nextIEEESingle();
}
out.value(dataArray);
}

===== Smalltalk =====
execute
|N fileName dataArray fileStream|

N := 100000.
fileName := 'dataFile.dat'.
fileStream := fileName asFilename readStream.
dataArray := (1 to:N) collect:[:i | fileStream nextIEEESingle].
out value:dataArray.
an alternative is:
...
dataArray := N timesCollect:[:i | fileStream nextIEEESingle].
...

=== Opening/Using Smalltalk/X Applications, Dialogs and Components ===

Any existing Smalltalk/X utility (both the one's which are provided with the base system, and even those coming from additional loaded Smalltalk code) can be called and used. For example, the following uses the builtin file dialog to ask for a directory.

===== JavaScript =====
execute() {
var answer;

answer = Dialog.requestDirectory("Please select an output folder:");
if ( answer.notEmptyOrNil() ) {
out.value( answer );
}
}

===== Smalltalk =====
execute
|answer|

answer := Dialog requestDirectory: 'Please select an output folder:'.
answer notEmptyOrNil ifTrue:[
out value: answer
]

Take a look at the "Dialog" class (using "''Extras''" - "''Tools''" - "''Class Browser''"),
where you'll find many common standard dialogs, for confirmations, simple questions, file dialogs etc.

=== Loading Additional Smalltalk/X Code ===

You can even create whole library or application packages, compile it as separate package, and load it dynamically to be used from within an elementary block. Assuming that a package named "myPackage.dll" (or "myPackage.so" under Unix/Linux) containing an application class named "MyApplication" has been created and is located in the expecco bin folder, the code can be loaded and executed with:

===== Smalltalk =====
execute
|answer|

Smalltalk loadPackage:'myPackage'. "/ checks if already loaded, to only load the first time called
MyApplication open.

To create your own applications or addons, download the free [http://www.smalltalk-x.de Smalltalk/X development IDE ] for development and package building.

== Expecco and Smalltalk API Stability ==

The Smalltalk/X class library has been around for more than 30 years now,
and of course grew over time.
We have always tried hard to keep the API backward compatible, in not removing existing methods, even when new methods appeared, which provided a similar or superset functionality.

Thus, code written 30 years ago can still depend on the interface and it is still working unchanged.

We will continue to keep this backward compatibility in the future,
to avoid breaking customer code, whenever possible (there were very few exceptions in the past, where obvious bugs had to be fixed, and customer code already depended on the wrong behavior).

That said, we must emphasize on that being only true for the ST/X class libraries themselves, and any officially published expecco APIs from this document.

If you use internal expecco functionality (which you may find when browsing in the class browser),
we cannot guarantee backward compatibility in future versions.
If you feel a need for using such an interface, please consult/inform eXept to either get help on a cleaner solution, and/or inform us that the API is used and to get your used interface be marked as "stable EXPECCO_API".

== Appendix ==

=== Smalltalk Language Syntax (BNF) ===

See also: [http://rosettacode.org/wiki/Category:Smalltalk Smalltalk Short Description (in rosettacode wiki)], [http://live.exept.de/doc/online/english/getstart/tut_2.html Smalltalk Basics]

;; Notice: an elementary Smalltalk action's "execute" method is a unary method (no argument).
;; there can be only one single such method in an elementary action (private functions should be defined as Smalltalk blocks)
;;
;; This is standard Smalltalk language, with Smalltalk/X language extensions
;;
method ::= selectorSpec body

selectorSpec> ::= unarySelectorSpec
| binarySelectorSpec
| keywordSelectorSpec

unarySelectorSpec ::= symbol

binarySelectorSpec ::= binopSymbol identifier

keywordSelectorSpec ::= ( keywordSymbol identifier )+

body ::= [ "|" localVarList "|" ] [statements]

localVarList ::= ( identifier )+

statements ::= statement
| statement "."
| statement "." statements

statement ::= expression
| returnStatement

returnStatement ::= "^" expression

expression ::= identifier ":=" expression
| keywordExpression

keywordExpression ::= binaryExpression
| binaryExpression ( keywordSymbolPart binaryExpression )+

binaryExpression ::= unaryExpression
| unaryExpression ( binopSymbol unaryExpression )+

unaryExpression ::= primary
| primary ( unarySymbol )+

primary ::= identifier
| literalConstant
| expandedStringExpression
| braceArray
| "(" expression ")"
| block
| "self"
| "super"

identifier ::= ( "_" | "a"-"z" | "A"-"Z") ( "_" | "a"-"z" | "A"-"Z" | "0"-"9" )*

literalConstant ::= integerConstant
| radixIntegerConstant
| floatConstant
| arrayConstant
| byteArrayConstant
| stringConstant
| characterConstant
| "true"
| "false"
| "nil"

integerConstant ::= ( "0"-"9" )+

radixIntegerConstant ::= base "r" baseDigits+

base ::= integerConstant (valid are: 2-31)

baseDigits := "0"-"9" | "A"-"Z" | "a"-"z" (valid are "0".."0"+base-1 and "a".."a"+base-10-1 and "A".."A"+base-10-1)

floatConstant ::= [ "-" ] [ digits+ ] "." [ digits+ ] [ ("e" | "E" | "d" | "D") [ "-"] digits+ ]

arrayConstant ::= "#(" literalConstant* ")"

byteArrayConstant ::= "#[" integerConstant(0..255)* "]"

stringConstant ::= ' characters... '
| cString

characterConstant ::= "$" character

block ::= "[" [ blockArgList ] body "]”

blockArgList ::= (identifier":" )*

comment ::= " " " any-character* " " " | eolComment

unarySymbol ::= identifier

binopSymbol ::= ( "+" | "-" | "*" | "/" | "\" | "," | "@" | "%" | "&" | "=" | "<" | ">" | "~" )+

keywordSymbolPart ::= identifier":"

keywordSymbol ::= keywordSymbolPart+

symbolConstant ::= "#"unarySymbol
| "#"binarySymbol
| "#"keywordSymbol
| "#'"any-character*"'"

==== Smalltalk/X Language Extensions (BNF) ====

Smalltalk/X provides a few very useful syntax extensions w.r.t. standard Ansi Smalltalk:

eolComment ::= " "/ " any-character-up-to-end-of-line

tokenComment ::= " "<<"TOKEN
...
any number of lines not beginning with TOKEN
(where TOKEN is any valid identifier string)
...
TOKEN

braceArray ::= "{" [ expression | expression ( "." expression )+ ] "}" (an array with computed elements)

literalObject ::= "#{" ( fieldName: constant )+ "}" (a constant object with getters for fields)

immediateObject ::= "{" ( fieldName: expression )+ "}" (an immediate object with getters and setters)

cString ::= c'string with C-escapes'

eString ::= e'string with C-escapes and {embedded expressions}'

iString ::= i'string with C-escapes and {embedded expressions} which is also internationalized'

typedArrayLiteral ::= #u8(...) "/ unsigned byte array constant
| #s8(...) "/ signed byte array constant
| #u16(...) "/ unsigned int16 array constant
| #s16(...) "/ signed int16 array constant
| #u32(...) "/ unsigned int32 array constant
| #s32(...) "/ signed int32 array constant
| #u64(...) "/ unsigned int64 array constant
| #s64(...) "/ signed int64 array constant
| #f32(...) "/ single precision IEEE float array constant
| #f64(...) "/ double precision IEEE float array constant

cStyleInt ::= 0xXXX
| 0oOOO
| 0bBBB

indexedAccess ::= array-expr "[" index-expr "]"
| array-expr "[" index1-expr "][" index2-expr "]"

indexedStore ::= array-expr "[" index-expr "]" := <expr>
| array-expr "[" index1-expr "][" index2-expr "]" := <expr>

=== JavaScript Language Syntax (BNF) ===

-- incomplete w.r.t. expression syntax -- to be added

;; Notice: an elementary JavaScript action's "execute" function
;; must be a unary function (no argument).
;; 
;; However, it is possible to define additional (private) helper functions.
;; These will only be visible within that single elementary action's code.
;; 
;; Also notice the syntax extensions for character constants and the "return from" statement.
;; 
method ::= functionSpec functionBody

functionSpec ::= ["async"] "function" identifier "(" [argList] ")"

functionBody ::= "{" (statement)+ "}"

statement ::= varDeclaration
| ifStatement
| whileStatement
| doStatement
| forStatement
| tryCatchStatement
| switchStatement
| returnStatement
| "{" (statement)+ "}"
| expression

varDeclaration ::= "var" identifier ( "," identifier)* ";"

ifStatement ::= "if" "(" expression ")" statement
[ "else" statement ]

whileStatement ::= "while" "(" expression ")" statement

doStatement ::= "do" statement "while" "(" expression ")" ";"

forStatement ::= "for" "(" [expression] ";" [expression] ";" [expression] ")" statement

tryCatchStatement ::= "try" statement (catchClause | finallyClause | catchFinallyClause)

catchClause ::= "catch" "(" identifier [identifier] ")" statement

finallyClause ::= "finally" statement

catchFinallyClause ::= catchClause finallyClause

switchStatement ::= "switch" "(" expression ")" "{" ("case constantExpression ":" statement)+ [ "default:" statement+ "}"

returnStatement ::= "return" expression [ "from" identifier ]

expression ::= term ( ("+" | "-") term)*
| "await" expression

term ::= factor ( ("*" | "/" | "%" ) factor)*

factor ::= powExpr ( "**" powExpr)*

powExpr ::= "typeof" "(" expression ")"
| "!" factor
| "-" factor
| "++" factor
| "--" factor
| primary "--"
| primary "++"

primary ::= identifier
| literalConstant
| arrayExpression
| "(" expression ")"
| block
| "this"
| "super"
| "new" classIdentifier [ "(" constant ")" ]
| functionDefinition
| lambdaFunction

functionDefinition ::= "function" [functionName] "(" [argList] ")" functionBody

lambdaFunction ::= "(" [argList] ")" "=>" functionBody
| arg "=>" functionBody
| "(" [argList] ")" "=>" expression
| arg "=>" expression

identifier ::= ( "_" | "a"-"z" | "A"-"Z") ( "_" | "a"-"z" | "A"-"Z" | "0"-"9" )*

literalConstant ::= integerConstant
| radixIntegerConstant
| floatConstant
| arrayConstant
| byteArrayConstant
| stringConstant
| characterConstant
| "true"
| "false"
| "null"

integerConstant ::= ( "0"-"9" )+

radixIntegerConstant ::= hexIntegerConstant | octalIntegerConstant | binaryIntegerConstant

hexIntegerConstant ::= "0x"hexDigit+

hexDigit := "0"-"9" | "A"-"F" | "a"-"f"

octalIntegerConstant ::= "0"octalDigit+

octalDigit := "0"-"7"

binaryIntegerConstant ::= "0b"binaryDigit+

binaryDigit := "0" | "1"

floatConstant ::= [ "-" ] [ digits+ ] "." [ digits+ ] [ ("e" | "E" | "d" | "D") [ "-"] digits+ ]

arrayConstant ::= "[" [literalConstant ("," literalConstant)*] "]"

arrayExpression ::= "[" [expression ("," expression)*] "]"

stringConstant ::= apos character* apos
| quote character* quote

characterConstant ::= "$" character

apos ::= "'"' (single quote)

quote ::= " " " (double quote)

comment ::= "/*" any-character* " */ " | eolComment

eolComment ::= " // " any-character-up-to-end-of-line

Notice the nonstandard extension for single character constants

----
Back to [[ Online_Documentation#Code_API_Overview Online Documentation ]]

[[Category: Advanced/en]]

Code Editor/en

2026-02-23T11:35:20Z

Sv: Änderung übernommen aus altem Wiki von cg, 12.2.26

== Introduction ==
[[Bild:Code Editor.png|thumb|300px|Code Editor]]
The code editor is used to view and edit the source code of an [[ElementaryBlock_Element/en | elementary block]]. It is found on the "''Code''" tab after selecting an elementary block in the navigation tree. The same editor is also used in all tools (File-Browser, Data-Viewers, Inspectors, Notepad, Documentation Editor, Debugger etc.)

An example for some code in the editor is shown on the right.

The editor consists of a language drop down list item at the top, and a code editor area, which covers the rest of the editor's space. The code input area is a regular text editor which provides syntax coloring and some code-related functions on its pop-up (right button) menu.

The drop down list selects the programming language in which the block is to be coded. If changed, the system tries to convert the current code into the newly selected language, which is only possible/supported for some language combinations. The block's icon is adjusted depending on the language.

When an elementary block is initially created, some template code is shown in the editor. This consists of the "<code>execute</code>" function body, a comment which gives advice on how to access the input and output values, and a transcript command which prints a standard output message to the transcript. Thus, the block can be immediately executed and does "something useful". Once you get familiar with elementary code, this template comment can be disabled via the settings menu ("''Extras''" → "''Settings''" → "''Look & Feel''" → "''Code Editor''" → "''Long Code Template''").

Usually, you will cut out the comment and the transcript command, and replace it by your own code. The function name and body delimiters should be left as is. While typing, a just-in-time parser performs syntax coloring and some syntactic and semantic checks. Most errors and typos are thus detected immediately at editing time.

The [[expecco API]] describes some appropriate method calls for JavaScript and Smalltalk. To access the full protocol of the underlying framework classes, use a system browser from the tools menu or refer to the [http://live.exept.de/doc/online/english/TOP.html "Smalltalk/X Online Documentation"] or the [http://live.exept.de/ClassDoc "Smalltalk/X Online Class Documentation"].

== Programming Language Awareness ==

==== Builtin Languages ====

Currently, two programming languages are built right into expecco. These are translated into an internal compact bytecode form whenever code is "''accepted''", and further compiled to machine code whenever the action block is first invoked. The languages are the system's underlying [[ Expecco_API#expecco_API | Smalltalk ]] language and a [[ Expecco_API#expecco_API | JavaScript ]] lookalike language, which follows the syntax of JavaScript, but has an object and inheritance model of the underlying Smalltalk system (i.e. it is class based, not instance based, and does not support dynamic change of an object's slot layout).

These built-in languages are fully supported by the code editor and the debugger: you can place breakpoints (or explicit "halts") into the code, single step, inspect local variables etc. Also, syntax coloring, code completion and quick syntax checking are supported for those built-in languages.

The API is described in the the "[[expecco API]]" document.
 The underlying Smalltalk system is described on the [https://live.exept.de/doc/online/english/TOP.html Smalltalk/X website]

==== Non Builtin (Bridged) Languages ====

For some languages a [[ElementaryBlock_Element/en#Bridged_Actions | bridge framework]] is provided. Bridges setup a communication channel to an external language interpreter. This interpreter is started once, when the very first such action is to be executed, and kept alive. So any internal state of the interpreter (open files, protocol channels, objects or frameworks) can be accessed by later actions.

For NodeJS and Python, debugging support is partially implemented or being developed.

[[ElementaryBlock_Element/en#Bridged_Actions | Bridged code execution]] is supported for:
* [[ElementaryBlock_Element/en#Groovy_Language | Groovy / Java]]
* [[ElementaryBlock_Element/en#Bridged_NodeJS_Actions | Node.js]]
* [[ElementaryBlock_Element/en#Python_Blocks_.28Bridged.29 | Python, Jython and IronPython]]
* [[ElementaryBlock_Element/en#Ruby_Blocks_.28Bridged.29 | Ruby]]
* [[ElementaryBlock_Element/en#Bridged_Smalltalk_Actions | Smalltalk (eg. on a remote machine)]]
* [[ElementaryBlock_Element/en#C Blocks (Bridged) | C ]]

==== Non Builtin (Script) Languages ====

Other (non-builtin) script languages are processed and executed by external interpreters, and the editor may not be aware of or support any language specific editing support. For some languages, syntax highlighting and comment detection is provided.
For other languages, neither breakpoints, nor single stepping, nor evaluation of expressions or inspection of values in the debugger are possible in general.

For example, shell and batch scripts are executed by forwarding the code to an appropriate command line interpreter.

[[ElementaryBlock_Element/en#Script_Action_Blocks | Script language]] programs written for
* [[ElementaryBlock_Element/en#Shell_Script_Blocks | Unix/Linux Shell]]
* [[ElementaryBlock_Element/en#Batch_Script_Blocks | Windows Batch]]
* [[ElementaryBlock_Element/en#AppleScript_Blocks | AppleScript]]
* [[ElementaryBlock_Element/en#Ruby_Script_Blocks | Ruby]]
* [[ElementaryBlock_Element/en#Node.js-Script_Blocks | Node.js]]
* [[ElementaryBlock_Element/en#Python_Script_Blocks | Python and Jython]]
* [[ElementaryBlock_Element/en#TCL.2C_Perl_and_Go_Script_Actions | Tcl, Perl and Go]]
* [[ElementaryBlock_Element/en#R_Action_Blocks | 'R']]
* [[ElementaryBlock_Element/en#Plot.2FGraph_Action_Blocks | GnuPlot]]
* [[ElementaryBlock_Element/en#GNU_Octave_Action_Blocks | GNU Octave (a Matlab clone)]]

are executed by an appropriate external scripting engine.

Debugging facilities are limited for those external languages (no single stepping, for example). Although not normally a major issue (as these languages are less used inside expecco), language support for those can be made available by defining an external language editor in the settings dialog. For example, under Windows, a Notepad++ or under Unix, an Emacs editor may be useful in some situations.

== Mouse Click and Selection ==

Single click the left mouse button to move the cursor.
Click and drag to select a piece of text.

Double click to select a word.
Double click and drag (not releasing the mouse button after the second click) will select more text word-wise.

Triple click to select a line.
Triple click and drag (not releasing the mouse button after the third click) will select more text line-wise.

Quadruple click to select the whole text.

The selection can extended either by pressing the mouse button and the <kbd>Shift</kbd> key simultaneously,
or the <kbd>Shift</kbd> key and one of the cursor keys. If no previous selection exists, the selection is extended from the previous cursor position.

A right button click shows the editor's menu, which contains more editing functions, including many useful operations in its "''Misc''" and "''More''" submenus.

== Special Characters ==
To enter special characters which are not on your keyboard and cannot be entered via <kbd>ALT</kbd>-key combinations, open a "special characters"-dialog via the popup menu ("''More''" → "''Special Characters''"). This presents all possible characters of the Unicode character set. This dialog can be used like a second keyboard; click on the character to get it inserted at the current cursor position. You can keep this window open and around to enter multiple characters.

== National Characters on International Keyboards ==
These can be entered either via the special characters dialog (found in the context menu under "''More''") or by enabling the dead key input feature (unless this is already done by your operating system). The dead key feature can be enabled globally for all editors (via the "''Settings''" → "''Look&Feel''" dialog), or for an individual editor via its context menu ("''More''" → "''Misc''" → "''Dead Keys''").

With dead keys enabled, type one of the diacritical character (i.e. quote, tilde, double quote, grave or acute) followed by a character. Press the Cursor-Right key or Space to get the diacritical character in isolation.

== Editor Functions and Keyboard Shortcuts ==

The editor provides the most common edit functions both via its right-button pop-up menu and via keyboard shortcuts.
For some functions, more than one keyboard shortcut is present (the reason is that on some systems, some shortcuts are reserved by the operating system or window manager, so that the alternative shortcut must be used, or that not all keyboards have all keys).

A more detailed description of the editor's features is found in the [http://live.exept.de/doc/online/english/getstart/TOP.html#EDITING Smalltalk/X online manual's "Editing Text" section].

The most useful operations are:
{| class="wikitable"
|-
! Function !! Shortcut (s) !! Description
|-
| Cut || <kbd>Ctrl-x</kbd> || Cut the selected text. The text is placed into the clipboard and can be pasted via Paste (also into other programs).
|-
| Copy || <kbd>Ctrl-c</kbd> || Copy the selected text. The text is placed into the clipboard and can be pasted via Paste.
|-
| Paste || <kbd>Ctrl-v</kbd> || Paste the previously copied or cut text (i.e. the text from the clipboard). The text can be pasted multiple times.
|-
| Paste Previous || <kbd>Ctrl-V</kbd> || Paste a previously copied or cut text (i.e. from the clipboard history).
|-
| Undo || <kbd>Ctrl-z</kbd> || Undo the previous edit operation or text insertion.
|-
| Redo || <kbd>Ctrl-y</kbd> || Undo the previous undo.
|-
| Delete || <kbd>Del</kbd> or <kbd>Backspace</kbd>|| Delete the selected text without affecting the clipboard. If nothing is selected, <kbd>Del</kbd> deletes the next character whereas <kbd>Backspace</kbd> deletes the previous.
|-
|colspan="3 style="text-align:center"|  
|-
| Again || <kbd>F8</kbd> || Repeat the previous cut or replace operation. Implies a search for the next occurrence of the affected text. This is a very useful function, eg. to replace multiple occurrences of a string by another, you double-click on the first, type over it, and press "''Again''" to repeat. The right-button menu also contains an "''Again For All''" function, which repeats the last operation for every occurrence.
|-
|colspan="3 style="text-align:center"|  
|-
| Goto || <kbd>Ctrl-g</kbd> || Goto a given line number
|-
| Find || <kbd>Ctrl-f</kbd> || Open a search / search+replace dialog
|-
| Find-Forward || <kbd>Cmd-f</kbd> || Search forward for the currently selected text or the previous searched text (if the text selection was unchanged).
|-
| Find-Backward || <kbd>Cmd-b</kbd> || Search backward for the currently selected text or the previous searched text.
|-
|colspan="3 style="text-align:center"|  
|-
| Begin of Line || <kbd>Pos1</kbd> or <kbd>Home</kbd> || Move the cursor to the first non space in the current line. If pressed again, move to the very begin. The key is labelled <kbd>Home</kbd> on many keyboards.
|-
| Begin of Page Begin of Text|| <kbd>Ctrl-Pos1</kbd> or <kbd>Ctrl-Home</kbd> || Move the cursor to the top of the page; press again to move to the top of the text
|-
| End of Line || <kbd>Ctrl-e</kbd> or <kbd>End</kbd> || Move the cursor to the end of the current line
|-
| End of Page End of Text|| <kbd>Ctrl-End</kbd> || Move the cursor to the end of the page; press again to move to the end of the text
|-
| Next-Word || <kbd>Ctrl-w</kbd> || Move the cursor to the next word. Press multiple times to advance
|-
| Select next Word || <kbd>Cmd-w</kbd> || Select the word under the cursor, the space between or the next word. Press multiple times to advance to the next word
|-
| Select plus Word || <kbd>Cmd-W</kbd> || Extends the selection by the next word under the cursor, the space between or the next word. Press multiple times to select more words
|-
| Select-Line || <kbd>Cmd-l</kbd> || Select the cursor line, the space between or the next word. Press multiple times to select more lines
|-
| Select-All || <kbd>Cmd-a</kbd> || Select the whole text
|-
| Select from Begin || <kbd>Cmd-A</kbd> || Select the text from start to the cursor
|-
| Select to End || <kbd>Cmd-E</kbd> || Select the text from the cursor to the end
|-
|colspan="3 style="text-align:center"|  
|-
| DoIt || <kbd>Ctrl-d</kbd> || Execute the selected text as a Smalltalk or JavaScript expression. If there is no selection, the whole contents of the current cursor line is executed.
|-
| PrintIt || <kbd>Ctrl-p</kbd> || Execute the selected text as a Smalltalk or JavaScript expression and paste the result
|-
| InspectIt || <kbd>Ctrl-q</kbd> || Execute the selected text as a Smalltalk or JavaScript expression and show the result in an inspector window
|-
| BrowseIt || <kbd>Ctrl-B</kbd> || Evaluate the selected text as a Smalltalk or JavaScript expression and open a class browser on the class of the result. If a class name is selected, that classes source code is shown.
|-
| ImpementorsOfIt || <kbd>Ctrl-I</kbd> || Open a class browser on all implementations of the selected message name. For C and Java programmers: all virtual functions in the system which implement the selected 'function' name are shown. Because methods are not functions, these are called "methods" in Smalltalk. Period.
|-

|colspan="3 style="text-align:center"|  
|-
| Indent || select+<kbd>Tab</kbd> || indent the selected line(s) or the current line if none is selected by one tab.
|-
| Undent || select+<kbd>Shift</kbd>-<kbd>Tab</kbd> || undent the selected line(s) by one tab
|-
| Indent4 || <kbd>F12</kbd> || indent the selected line(s) by 4
|-
| Undent4 || <kbd>F11</kbd> || undent the selected line(s) by 4
|-
| Indent1 || <kbd>F10</kbd> || indent the selected line(s) by 1
|-
| Undent1 || <kbd>F9</kbd> || undent the selected line(s) by 1
|-
| Change Case || <kbd>F6</kbd> || toggle the selection between UPPERCASE, Titlecase and lowercase
|-
| Rename || <kbd>F2</kbd> || rename a variable (not supported by all programming language editors)
|}

The <kbd>Cmd</kbd> key is usually labeled "Cmd", "Alt" or "Meta", depending on your keyboard.
 To search text that is already on the screen, select it and press <kbd>Cmd-f</kbd> (or <kbd>Cmd-b</kbd> to search backward).
 If it is not already visible, press <kbd>Ctrl-f</kbd> to get a search dialog.
 To evaluate and paste the result, select some text and press <kbd>Ctrl-p</kbd>.
 To replace a string with another, select it, type in the new text, and press <kbd>F8</kbd> (Again) - and again, and again... The popup meny also contains an "Again for All" entry, which repeats this til the end of the text.
 If you want to search first, before replacing, alternate between <kbd>Cmd-f</kbd> (Forward search) and <kbd>F8</kbd> (Again) or use the search dialog, which also offers a search and replace function.

==== DoIt and PrintIt ====

Especially the "''DoIt''", "''PrintIt''" and "''InspectIt''" functions deserve more explanation as they are often very useful.
These are avilable in the builtin languages (Smalltalk and JavaScript) and interpret the selected text as a code fragment of the programming language and execute it. For example, if you select "<code>Math.sin(45.degreesToRadians)</code>" in a JavaScript editor, then press the "''PrintIt''" shortcut (<kbd>Ctrl-p</kbd>), that code is interpreted and the result pasted at the cursor position.
 Useful JavaScript expressions are:
Date.today()
Time.now()
UUID.new()
OperatingSystem.getHostName()
OperatingSystem.getSystemInfo()
OperatingSystem.isMSWindows()
1234567.nextPrime()
1234567.nextPowerOf2()
Math.sin(45.degreesToRadians())

or in Smalltalk:
Date today
Time now
UUID new
OperatingSystem getHostName
OperatingSystem getSystemInfo
OperatingSystem isMSWindows
1234567 nextPrime
1234567 nextPowerOf2
45 degreesToRadians sin
10 kilo ohm * 23 milli ampere

Of course, this immediate expression evaluation is very useful while programming an elementary block. You can try out code fragments right in the editor.
By the way: every window which shows code can evaluate code: the elementary block editor, the workspace windows and especially the debugger. In the debugger, local variables and ''self'' (''this'') can be used in evaluated code.
For incremental programming, place a halt in your elementary block's code, and write the program (after testing it with doIt/printIt) right in the debugger (Click on the "''Resend''" button after a change, to restart the changed function's code).

For a full list of useful expressions, please refer to the [http://live.exept.de/doc/online/english/TOP.html Smalltalk/X Online Documentation].
The debugger's documentation is found in the [http://live.exept.de/doc/online/english/tools/debugger/TOP.html Smalltalk/X Tools Documentation].

==== Again (Repeat Last Edit) ====
The "''Again''" operation (press <kbd>F8</kbd> or select it from the operations (= right-button) menu) repeats the last delete or replace operation, after searching for the next occurrence of the original string. So, to incrementally rename all occurrences of "foo" with "bar", find the very first occurrence "foo", select it, type "bar" over it. This is the first edit operation. Then press <kbd>F8</kbd> to repeat this for the next occurrence of "foo" in the text.

The operations menu also offers an "''Again until End''" function in its "''More"'' sub-menu. This performs multiple "''Again''" operations, until the original string is no longer found. Use this to replace ALL occurrences of a string by another.

==== Additional Useful Editor Commands ====
The popup-menu and especially the submenus under "''More''", "''Tools''" and "''Other''" contain a number of additional, often very useful editor commands. Among many others, will find functions to paste the current date and time, to generate UUIDs or to sort your text alphabetically or by columns. Very useful functions are also "''Open Filebrowser on Selected Name''" and "''Open Webbrowser on Selected URL''", which are enabled if the current selected text looks like a valid filename or URL.

== Editor Customization ==
=== Line End Behavior ===
By default, the editor is configured to treat the whole page like a piece of paper, where the cursor can be arbitrarily positioned. If you move the cursor, or click into the view, any short line will be automatically lengthened to the current cursor position, when a non-blank character is entered ("''Rand-editor behavior''").

This may be an unusual behavior if you are used to vi, emacs, notepad and other editors, which only allow positioning of the cursor to the actual line end, without automatic line lengthening. If you prefer this behavior, go to the editor's settings dialog ("''Extras''" → "''Settings''" → "''Look & Feel''" → "''Code Editor''") and toggle the "''Standard Line-End Behavior''" toggle. However, if you do so, it is probably a good idea to also check the "''Automatic Indent''" toggle.

Expecco 26.1 also adds a popup menu item in the editor ("''More''" → "''Misc''" → "''Rand Cursor Behavior''") to change this in a single editor.

=== Edit Tab Stops ===
The default is multiples of 8.

This can be changed for an individual editor via its popup menu ("''More''" → "''Misc''" → "''Toggle Tabs''") or as a default setting via the settings ("''Extras''" → "''Settings''" → "''Look & Feel''" → "''Code Editor''").

Although the default is 8, we recommend and use a 4-space tab setting at exept; tab8 makes the text too wide and will lead to a lot of horizontal scrolling, whereas tab2 makes it harder to see the control structure quickly.

=== Tab Stops when Writing Files ===
When saving text to a file, leading spaces in multiples of 8 are replaced by a tab.

[[Datei:point_right.png|20px]] Notice: This conversion is independent of your ''edit tab setting''. 
In the file, tab stops are always in multiples of 8.

This was done to prevent unintended corruption especially of makefiles,
which require tab characters to be present.

In case you have to change a file's tab interpretation, use a file browser (or external editor).

In the file browser, the behavior can be changed to either 4 spaces per tab, or to no tab generation, via its own "''Extras''" → "''Tab Stop Conversion''" menu.

This may also be an unusual behavior if you are used to vi, emacs, notepad and other editors, which treat the edit-tab setting the same as the file's tab setting.

=== Changing the Keyboard Mapping ===
The editor's keyboard-to-command mapping is loaded at startup time from a file named "<code>keyboard.rc</code>" in the expecco installation folder. Once you get a little familiar with the syntax, you may even change the keyboard mapping and/or add additional macro functions to suit your personal preferences.
Detailed information on how this is one in found in the [http://live.exept.de/doc/online/english/custom/TOP.html#KEYBOARD Smalltalk/X Documentation on Keyboard Customization].

=== Insert Mode vs. Overwrite Mode ===
Is toggled via the popup menu of the "I"-insert indicator at the bottom right of the window, or under the "''More''" submenu of the editor's context (right-click) menu.

== Other Useful Functions ==
A number of functions are found under the "''More''" and "''Tools''" items of the popup menu.
Useful are:
* "''Open WebBrowser on Selection''" - takes the selected text as an URL and opens a browser for it
* "''Open FileBrowser on Selection''" - dimilar for file names

* "''Sort''" - sort the selected lines by various criteria (eg. column number)

* "''Insert UUID''" - to generate a new, globally unique identifiers

== Break- and Tracepoints ==
To toggle a breakpoint, double-click into the area left of the line-number, where the breakpoint or tracepoint should be placed. With shift pressed, a tracepoint will be placed, without shift, a breakpoint is toggled.

Breakpoints will open a debugger, tracepoints will simple send a trace message to the Transcript window (which should obviously be open).

The debugger allows for stepping, aborting or continuing.

[[Datei:point_right.png|20px]] Notice: you can also get into a debugger by pressing the interrupt key (<kbd>CTRL</kbd>+<kbd>.</kbd>, <kbd>CMD</kbd>+<kbd>.</kbd> or <kbd>Pause</kbd>) or by clicking on the "''Interrupt & Debug''" icon at the top right.

[[Datei:point_right.png|20px]] Notice also, that not all language interpreters will handle interrupts at any time - especially interrupts while waiting for I/O or while setting up socket connections are uninterruptable in many interpreters (i.e. Node and Python), in contrast to the builtin languages ST and JS, which are interruptable and proceedable.

== Use of an External Editor ==
If you prefer to use an external text editor, navigate to the externalTools Settings ("''Extras''" → "''Settings''" → "''External Tools''") and enter the path to your editor into the "''Code Editor''" field.
If that field is non-empty, an icon is shown in the elementary action's code page, which calls the configured editor on the current text.
 A very powerful editor for any operating System is [https://code.visualstudio.com/download VisualStudio Code],
other good editors for Windows are [https://notepad-plus-plus.org/downloads "notepad++"], [https://www.gnu.org/software/emacs/download.html "Emacs"] and [https://www.scintilla.org/SciTEDownload.html "SciTE"].

If an external editor is opened, expecco waits for the editor's executable to finish, then reads back the edited file.
Some of the above commands will need an additional command line argument to ensure this (see the offered command list in the settings dialog for concrete examples).

Be aware that some apps take some time to start; it is therefore probably only useful for large scripts or if special language editing features are required (eg. code completion). You have to configure the editor, in order for any imported packages/source to be shown correctly.

== See Also ==

[[Scheme_Editor | Scheme Editor]]

For the programmer API for the builtin languages see: [[Expecco API]],
 
Sections of interest are the [[Expecco_API/en#Pin Functions | Pin-API ]], [[ Expecco_API/en#Current Activity | Activity-API ]]

==== Language specific info ====
is found in the API chapters on:
     [[Expecco_API/en#JavaScript_and_Smalltalk_Elementary_Blocks|JavaScript and Smalltalk (builtin)]],
     [[Expecco_API/en#Groovy_Elementary_Blocks|Groovy (bridged)]],
     [[Expecco_API/en#Node.js_.28Bridged.29_Elementary_Blocks|Node (bridged)]],
     [[Expecco_API/en#Bridged_Python_Elementary_Blocks|Python (bridged)]],
     [[Expecco_API/en#Bridged_C_Elementary_Blocks|C (bridged)]]
     [[Expecco_API/en#Bridged_Ruby_Elementary_Blocks|Ruby (bridged)]],

Functions of the underlying expecco runtime system are accessible via JavaScript or Smalltalk elementary actions.
For information on the functions available in the built-in classes (method protocol), please refer to the [http://live.exept.de/doc/online/english/classDoc/TOP.html Smalltalk/X Online Documentation] and especially the [http://live.exept.de/ClassDoc Class Reference].
For example, some of the mathematical functions are described [http://live.exept.de/ClassDoc/classDocOf:,Number#Number_category_mathematical%20functions here]
and String processing functions are found [http://live.exept.de/ClassDoc/classDocOf:,String here] and [http://live.exept.de/ClassDoc/classDocOf:,CharacterArray here].
 
For elementary blocks in general, see [[ElementaryBlock Element]]
 
More information on the Debugger and Inspector are found in the tools section of the [http://live.exept.de/doc/online/english/tools/TOP.html Smalltalk/X Online Documentation].

====Shell and CMD scripts====
    [[Shell_Environment_Variables/en|Environment Variables]]



[[Category:Editors]]

PhysicalValues/en

2026-02-23T11:32:32Z

Sv: Änderung übernommen aus altem Wiki von cg, 27.1.26

Notice: the physical values package as described here is still considered "work in progress" and provided as a preview feature. However it is quite stable and tested by an exhaustive test suite).
We hope to have transcribed nature constant values and unit conversion factors correctly from public information (mostly wikipedia).
Please report any errors or inconveniences (or wishes) to exept.

== Introduction & Motivation ==
In the past, a number of big projects failed or went completely out of budget due to misinterpretations of data. An example well known to insiders (but not named here) lead to millions of loss due to some misinterpretation of metric versus imperial values in documentation and software. In addition, some units are even different in imperial vs. american systems.

Expecco supports values with units, to represent physical values such as length, acceleration, area, volume, mass, temperature, electric current etc.

Physical values are useful for a nicer presentation of measurement values (e.g. in a report) and to convert between unit systems (e.g. metric vs. imperial vs. US). They can also make elementary code which computes physical values more readable and more robust. And if the correct unit is returned from an expression, you know that you used the correct formula (or at least: not completely wrong).

Physical values are implemented by the underlying Smalltalk system and can be used both in Smalltalk and in JavaScript elementary blocks. Similar public domain packages might be available for Java or Node. There is at least on such package available for Python (see "astropy"). These can be installed with "npm" or "pip". However, there are currently no plans to transparently support exchange of physical values between expecco and Node, Java or Python. There is some support for Python's astropy quantities. If required, these should be passed as composite "<code>{ unitAmount:xxx unit:xxx }</code>" or objects and converted in the bridge as required. Sorry, but there exists as yet no commonly used encoding standard for such data (e.g. in JSON).

The following document describes the programmer's API for elementary Smalltalk and JavaScript actions. Corresponding types are found in datatype menus under the "''Physics''" group.

This document is meant for "experts" who understand some minimum Smalltalk syntax (which is easy). It will help to write your own eleemntary code in case you need additional functionality.

== No Warranty ==

The nature constants and conversion factors have been taken from wikipedia and other sources.
 We do not guarantee for their correctness. For some, new measures might give different values. If you encounter any errors or know about newer/better values, please let us know.

We recommend that you add additional verification/check actions (which should run before). A typical example wcould be:
self '''assert:'''(1 '''pound''' '''printString''' = '453.59237 g').
That code will also document any of your expectations.

== Motivating Examples ==

The nice thing about using values with units is that you will get a better feedback if the used formula is correct (at least from the units point of view - forgotten scalar constants in physical expressions are still undetected). If you get an unexpected or strange unit in your result, you will certainly have an error in your computation.

Take these as examples and don't take the values for granted: please let us know, if there are any errors in those examples (the author is not an electrical engineer ;-).

=== Example1: Metric vs. Imperial Units ===
Need to convert millimeters to inches, or know how thick a 3 AWG wire is?
 Simply [[Tools_Notepad/en#Code_Evaluation|evaluate ("''doIt''")]] in a notepad or smalltalk elementary action's codeview:
10 '''milliMeter''' '''asInches'''
=> 0.393700787401575 in
or
(Physic::Length '''awgDiameter''' '''unitAmount:'''3) '''asMilliMeter'''
=> 5.82733981304513 mm
or:
(PhysicalUnit '''unit:''''awg' '''amount:'''3) '''asSquareMillimeter'''

or:
(1 '''british''' '''gallon''') '''asMilliLiter'''
=> 3785.411784 ml
(1 '''american''' '''gallon''') '''asMilliLiter'''
=> 4546.09 ml

=== Example2: Time to Load a Cap (i.e. RC time constant) ===
You want to compute how long it takes to load a 100uF capacitor, given a 5V supply and a current limiting resistor with 100 kOhm?

First, compute the RC time constant; the electric charge (in Coulomb) transported through a wire is:
charge = I*t (I = current in Ampere; t in Seconds)
and the charge (in Coulomb) of a capacitor is:
charge = C*U (C = capacity in Farad; U = voltage)

We can immediately compute the electrical charge (in Coulomb) with the formula (C*U):
(5 '''volt''' * 100 '''micro''' '''farad''')
and get the result:
(1/2000) C
Notice that the above is Smalltalk syntax, and can be written exactly like that in a Smalltalk action.

We can also compute the current through the loading resistor (I = U / R) as:
5 '''volt''' / 100 '''kilo''' '''ohm'''
and get the result:
50 µA

To compute the time, equate and rearrange the above formulas:
(C * U)
t = -------
I

with I = U / R, we get:

(C * U)
t = -------
(U / R)

in Smalltalk (*):
t := (5 '''volt''' * 100 '''micro''' '''farad''' ) / (5 '''volt''' / 100 '''kilo''' '''ohm''')

and will get the RC time for t as:
10s

In other words, Smalltalk automatically found the correct result unit from the above computation and figured, that the result must be a time duration given in seconds.

(*) obviously, we could have further simplified the formula, or ask expecco to simplify it for us with:
:: <CODE>Physic::Expression '''simplify:''''(U * C) / (U / R)'</CODE>
:or:
:: <CODE>'(U * C) / (U / R)' '''asPhysicExpression''' '''simplified'''</CODE>
:which both give the result:<CODE>C * R</CODE>
:So, we could have also computed:
:: <CODE>t := 100 '''micro''' '''farad''' * 100 '''kilo''' '''ohm'''</CODE>
:and also get the same 10 seconds as result.

The capacitor's voltage will grow along a logarithmic curve, and is not fully charged after its RC time constant (its roughly 2/3 loaded).
Typical approximations will go for a 90% load, taking 3-5 times the RC time constant. (see wikipedia)

=== Example3: Signal Rise Time ===

Of course, you may also get the time with a given delta-voltage and current flow. From the formula:
I = C * ΔV / Δt.
we get:
Δt = C * ΔV / I
As an example, if an output pin of an IC drives 10mA, and it is connected to an input pin with 100pF input capacitance to ground, it will take:
100 '''pico''' '''farad''' * 5 '''volt''' / 10 '''milli''' '''ampere'''
to get it from 0V to 5V (in this case: 50ns).

=== Example4: Bandpass Filter Frequency ===

A filter's frequency is computed as:
1
f = ------------
2*π*R*C

What is the frequency, given 1 Megaohm and 0.1 Microfarad as values?
 In Smalltalk:

|r c f|
r := 1 '''mega''' '''ohm'''.
c := 0.1 '''micro''' '''farad'''.
f := 1 / (2*Float '''pi''' * r * c)

result:
f = 1.59154943091895 Hz

=== Example5: Capacitance of a Wire ===

Assume that there is a 10 cm long connection between 2 pins on a printed circuit board, and the connection faces a ground plane at a distance of 0.7 mm. The trace has a width of 0.5 mm.
 What is the capacitance of the wire, and how long does it take the output to rise from 0 to 5 V if it can drive 10 mA?.

The capacitance is:
C = ε0 * a / d
where ε0 is the [https://de.wikipedia.org/wiki/Elektrische_Feldkonstante permittability constant], a is the area and d is the distance of the capacitor's plates. We take the vacuum permutability as an approximation (strictly speaking, that is incorrect; it should be replaced by the printed board material's value and also depends on the frequency [https://en.wikipedia.org/wiki/Permittivity]). The trace has an area of 10 cm by 0.5 mm, and has a distance of 0.7mm from the ground plate. Thus we get:
a := 10 '''centi''' '''meter''' * 0.5 '''milli''' '''meter'''. "area"
d := 0.7 '''milli''' '''meter'''. "distance"
e0 := Physic::NatureConstants '''vacuumPermittivity'''. "ε0"
C := e0 * a / d.
or:
C := Physic::NatureConstants '''vacuumPermittivity''' "ε0"
* (10 '''centi''' '''meter''' * 0.5 '''milli''' '''meter''')
/ 0.7 '''milli''' '''meter'''.
that gives us 0.63 pF.
According to the above Example2, we can compute the signal's rise time as:
0.63 '''pico''' '''farad''' * 5 '''volt''' / 10 '''milli''' '''ampere'''
which gives: 315 ps
 or as a frequency:
1 / 315.0 '''pico''' '''seconds'''
=> 3174.60317460317 Mhz

=== Example6: E = mcˆ2 ===

Energy content of 1 gram of (rest) mass:
c := Physic::NatureConstants '''lightspeed'''.
1.0 '''gram''' * c '''squared'''
=> 89.8755178736818 TJ

c := Physic::NatureConstants '''lightspeed'''.
(1.0 '''gram''' * c '''squared''') '''asKiloWattHours'''
=> 24965421.6315783 kWh

c := Physic::NatureConstants '''lightspeed'''.
(1.0 '''gram''' * (c ** 2)) '''asMegaWattHours''' '''rounded'''
=> 24965 MWh

We'd love to use antimatter for energy supply!

=== Example7: Gravitational Force ===

F = (m1 * m2) * G / rˆ2

Force on two masses separated by one meter:
m1 := 1 '''kiloGram'''. "/ or kilo gram
m2 := 1 '''kiloGram'''.
G := Physic::NatureConstants '''gravitationalConstant'''.
r := 1 '''meter'''.
(m1 * m2 * G) / r '''squared'''
=> 6.6743e-11 N
or (in one expression):
(1 '''kiloGram''' * 1 '''kiloGram''' * (Physic::NatureConstants '''gravitationalConstant''')) / 1 '''meter''' '''squared'''
=> 6.6743e-11 N

How long will it take till they touch (in space without other gravitional fields around):

By F = m * a, we get the acceleration a = F / m; assuming m1 = m2 = 1 kg, we get the above divided by m1:
a = (m * G) / r '''squared'''
and, to get from an acceleration to the distance:
s = (a/2) * t^2, from which:

t = sqrt ( 2*s / a)

since the masses are the same 1 kg, each has to move half the distance; thus:
t := ( 1 meter / ((1 kiloGram * G) / 1 meter squared)) sqrt
=>122404.43 s
or (asHours):
=> 34.001 h
(I did not expect this happening so fast; if there is an error, let me know... ;-) )

Oh, I found out myself; sorry for my mistake: the acceleration increases when the distance gets smaller, but the above calculation was made with a constant acceleration, which is wrong!.
 So the formula is actually more complicated (integral of a differential equation). In fact, they touch even earlier: after only roughly 96000 seconds or 26.7 hours !!!
 The actual formula is:
Float pi * ( 1 meter cubed / (8 * G *(1 kiloGram + 1 kiloGram)) ) sqrt
=> 96136.215 s

=== Example8: British Drinking vs. US Drinking ===
Who gets most bang for the glas in a pub:
British, US or German drinkers?

1 '''british''' '''pint''' => 568.26125 ml
1 '''american''' '''pint''' => 473.176473 ml
(1/2) '''liter''' => 500 ml

Ok, lets go to the next british pub!

=== Example9: Potential Energy ===
The potential energy of 10 gram lifted 1 meter (m*h*G) is on earth:
10 '''gram''' * 1 '''meter''' * (Physic::NatureConstants '''earthGravity''') => 0.0980665 J
or alternatively:
10 '''gram''' * 1 '''meter''' * (Physic::NatureConstants '''astronomicalObjects'''['earth']['gravity']) => 0.0980665 J
or even:
10 '''gram''' * 1 '''meter''' * (Physic::NatureConstants '''earth''' '''gravity''') => 0.0980665 J
Note: astronomicalObjects returns a collection which can be indexed by 'earth', 'moon', 'mars' etc.
This returned object can then further be indexed by 'gravity', 'mass', etc.
The "earth'-message in the 3rd example also returns the earth's data.
 To see what is there, inspect the returned object.

=== Example10: Voltage at a Loudspeaker ===
Lets assume, we want to get 20 Watt out of a 4 Ohm loudspeaker. Which voltage will we need (only assuming non-complex resistance).
 The formulas are:
P = U * I (power is voltage times current)
and
U = R * I (voltage drop is resistance times current).
Lets rewrite into
U = P / I
and
I = U / R.
Then replace I in the first formula to get
U = P / (U/R)
or
U = (P * R) / U
Multiply both sides by U, we get:
U^2 = P * R
or
U = SQRT( P * R)

Lets evaluate (Smalltalk code here!):
(20 '''watt''' * 4 '''ohm''') sqrt => 8.9443 V

(you'll need an up-to-date version of expecco for this, as previous versions did not recognize square roots of formulas correctly, delivering a funny unit as result).

=== Example11: Energy of a Photon ===

The frequency f of a photon with a wavelength of 550 nanometer is:
f := Physic::NatureConstants '''c''' / 550 '''nano''' '''meter'''
=> 545.077 THz
and its energy is the Planck constant h times the frequency:
e := Physic::NatureConstants '''h''' * f
=> 3.61171974027078e-19 J
in electron volts gives:
e '''asElectronVolts'''
=> 2.25425815333091 eV

== Physic Package Loading ==

If you have an older expecco version, the physic packages (<CODE>stx:goodies/physic/units</CODE> for units and <CODE>stx:goodies/physic/formula</CODE> for formula parsing) may not be already loaded.
 If not, either add it to the list of required packages of your test suite or evaluate:
Smalltalk '''requirePackage:''''stx:goodies/physics/units'.
Smalltalk '''requirePackage:''''stx:goodies/physics/formula'.
in either an elementary action or in the startup file ("<code>expeccoStart.rc</code>").

All physic classes will be found in the "<CODE>Physic</CODE>" namespace (i.e. class names are prefixed with "<CODE>Physic::</CODE>" as in "<CODE>Physic::Energy</CODE>" or "<CODE>Physic::Volume</CODE>").

== Programming Language API==

'''Smalltalk'''
 As you'll have noticed, Smalltalk has a convenient syntax, for this kind of framework: you can immediately write code like:
1 '''kilo''' '''meter''' / 10 '''minutes'''
to compute a velocity.

'''JavaScript'''
 Due to the fact that the builtin Javascript also allows for numbers to be treated like objects, the same code written in JavaScript still looks somewhat readable:
1.'''kilo'''().'''meter'''() / 10.'''minutes'''()
although the parentheses make the code somewhat ugly.

All code fragments in the following document are written in Smalltalk syntax (add periods and parentheses to get the corresponding JS code).

== Units ==
=== Base Units ===

All [https://en.wikipedia.org/wiki/SI_base_unit base units] are measured in their corresponding [https://en.wikipedia.org/wiki/International_System_of_Units SI standard] units and print with an appropriate scaling prefix. I.e. by default, the unit chooses a "reasonable" prefix.

For example, a mass which has a [https://en.wikipedia.org/wiki/SI_base_unit base unit] of kilogram ("kg"), will print itself as "kg', 'mg', 'µg' etc. depending on its magnitude.

Explicit converters can be used to enforce a particular unit printing (e.g. if you insist on printing a mass in pounds, in grams, etc.) or if you want to enforce a particular scaling SI prefix (e.g. to enforce printing output in "cm" instead of "m" or "mm").

See examples below on how those converters affect the printout of a value.

Independent from any enforced print format, the internal representation of physical values is always using base unit amounts (i.e. SI units).

Base units are:
Unit Name Smalltalk Description
-----------------------------------------------
s Second second [https://en.wikipedia.org/wiki/Time time]
m Metre metre or meter [https://en.wikipedia.org/wiki/Length length]
kg Kilogram kilogram [https://en.wikipedia.org/wiki/Mass mass]
A Ampere ampere [https://en.wikipedia.org/wiki/Electric_current electric current]
K Kelvin kelvin [https://en.wikipedia.org/wiki/Thermodynamic_temperature temperature]
mol Mole mole [https://en.wikipedia.org/wiki/Amount_of_substance amount of substance]
cd Candela candela [https://en.wikipedia.org/wiki/Luminous_intensity luminous intensity]

To get a constant physical value in your Smalltalk code, write a [[Number_API_Functions|number]] followed by the unit name (in lowercase). For example:

1 second => 1s
1 meter => 1 m
1 kilogram => 1 kg
1 ampere => 1 A
1 kelvin => 1 K
1 mole => 1 mol
1 candela => 1 cd

(in other words: there are a number of methods defined in the [[Number_API_Functions|Number]] class,
which take the receiver and construct a corresponding unit instance from it. These methods are named after the SI unit names).

=== Derived Units ===
Additional [https://en.wikipedia.org/wiki/SI_derived_unit derived units] are:

Unit Name Smalltalk Description
-------------------------------------------------------------
V Volt volt voltage
Hz Hertz hertz frequency
m/s Meter per Second meterPerSecond speed, velocity
m/s² m/s per Second meterPerSecondPerSecond acceleration
m² Square Meter squareMeter area
m³ Cubic Meter cubicMeter volume
pa Pascal pascal pressure
W Watt watt power
N Newton newton force
J Joule joule energy
Ω Ohm ohm electric resistance
S Siemens siemens electric conductance
C Coulomb coulomb electric charge
F Farad farad electric capacitance
H Henry henry electric inductance
T Tesla tesla magnetic flux density
rad Radian radian angle
sr Steradian steradian solid angle
° Degrees degrees angle

Plus possibly more, by the time you read this.
There are a number of less frequently used derived units, for which no Smalltalk shortcut exists.
These might result from computations with physical values or be instantiated by sending explicit constructor messages to the unit (instead of sending a message to a [[Number_API_Functions|number]]).
 These are described below.

=== Converting Units ===
By default, values are presented as SI units. However, you may want to convert the to other unit systems. For this, converting units are provided.
These present a value in another unit system. For example as a value in imperial units (Inches, Pounds, etc.). Like all physical values they keep the actual amount internally in multiples of the SI base unit (metric), but will show the value with some scaling and with another unitString (eg. 'lb' or 'ft').

You can ask any other unit (usually a base unit) for a converting unit via getter messages, or by asking for a unit by its formula or by name.
 For example, you can ask the Length base unit for a number of common converting units:
Physic::Length yards => a unit which presents its metric amount in yards
Physic::Length inches or inches
Physic::Length feetAndInches ...he's 5 foot 2, he's 6 foot 4...
Physic::Length angstrom => a unit which presents its amount in angstrom
Physic::Length lightYears or light years
Physic::Length awgDiameter => presents its amount as american wire gauge diameter
and then create a value for it with the "<code>unitAmount:</code>" message.
 This will generate a value in multiples of the message-receiver's unit, as in:
Physic::Length yards unitAmount:5 => 5 yd
The list of converting units available per unit is shown below.

=== Scaling Units ===
As already mentioned above, unit values by default determine themself how small or large amounts are printed. For example, the Length unit will print amounts with an SI scale (kilo, mega, milli, etc.). Thus, when the value "4.5 milli meter" is printed (or displayed), it will present itself as "4.5 mm" (not as "0.45 cm" or "0.0045 m"). The scale used depends on heuristic and is chosen to conform to usual human written conventions.

You can convert any physical value to one where this heuristic is overwritten and an explicit SI-scale is preferred.
For this, use a ''Scaling Unit''. Specifying an explicit scaling unit is useful if you want to present values in a table or if you have to export values in a particular scale to some other program. Notice that the value of the scaling unit instance is still same - the only difference is how it prints itself.

Scaling units will print the amount with an explicit scale. Any unit can be asked for a scaling unit, although not all combinations are typically used in real live: for example, no-one would write "2 Hm" (hecto meter) or "1 Mm" (mega meter).
 You can get a scaling unit from any other unit with one of:
nanoUnit, microUnit, milliUnit, centiUnit, deciUnit, hectorUnit, kiloUnit, megaUnit, gigaUnit, etc.
(any of the possible scaling prefixes listed below concatenated with "Unit")

Similar to the above, you can create values with "<code>unitAmount:</code>", as in:
Physic::Mass pounds kiloUnit unitAmount:2
to create a mass of "2 kilo pounds (imperial)" which prints itself as "2 klb".
 Or:
Physic::Frequency kiloUnit unitAmount:10
to enforce that the frequency will be printed in kilohertz.

There is also a special "<code>unitUnit</code>", which prints its values as SI base units (without any scaling prefix). Use this eg. to enforce a length value to always print itself as meters.

Conversion methods are also available on values. Every physical value can be converted using one of the messages:
asKiloUnitValue, asMilliUnitValue, asMicroUnitValue, etc.
And you get a base unit value using "<code>asUnitUnitValue</code>".

Thus, "<code>4.5 milli meter asCentiUnitValue</code>" will present itself as "0.45 cm"
and "<code>4.5 milli meter asUnitUnitValue</code>" as "0.0045 m".

=== Unit vs. BaseUnit ===

As described, there are base units (eg. Meter, Kilogram, etc.) and their combinations (eg. Acceleration, Velocity, Energy ec.) and converting units such as Imperial Pound, Feet, Nautical Mile etc.

Every unit understands two pairs of value generator and value extracting messages:
unitAmount: / unitAmount
and:
baseUnitAmount: /baseUnitAmount
the unitAmount is the amount in that value's converted amount (eg. in Feet or Acre), whereas the baseUnitAmount is always the amount in the SI base or combination unit (eg. in Meter or SquareMeter).

Thus, every length unit will return a length of 1 meter if created with the "baseUnitAmount:" instance creation message; independent on how it will later be printed.

And every length unit will return a length with its own scale value via the "unitAmount:" creation message. For base units and directly derived units, the baseUnitAmount it the same as the unitAmount.

For example:
(Physic::Length '''unitAmount:'''2) => 2 m
(Physic::Length '''baseUnitAmount:'''2) => 2 m

(Physic::Length '''feet''' '''unitAmount:'''2) => 2 ft
(Physic::Length '''feet''' '''baseUnitAmount:'''2) => 6.56167979002624 ft (because 2 meters - the base unit value - is 6.56 ft)

(Physic::Length '''unitAmount:'''2) '''unitAmount''' => 2
(Physic::Length '''baseUnitAmount:'''2) '''unitAmount''' => 2
(Physic::Length '''unitAmount:'''2) '''baseUnitAmount''' => 2
(Physic::Length '''baseUnitAmount:'''2) '''baseUnitAmount''' => 2

(Physic::Length feet '''unitAmount:'''2) '''unitAmount''' => 2
(Physic::Length feet '''baseUnitAmount:'''2) '''unitAmount''' => 6.56167979002624
(Physic::Length feet '''unitAmount:'''2) '''baseUnitAmount''' => 0.6096
(Physic::Length feet '''baseUnitAmount:'''2) '''baseUnitAmount''' => 2

(Physic::Length '''unitAmount:'''10000000) '''unitAmount''' => 10000000
(Physic::Length '''meter''' '''unitAmount:'''10000000) '''unitAmount''' => 10000000
(Physic::Length '''meter''' '''unitAmount:'''10000000) '''baseUnitAmount''' => 10000000
but when printed:
(Physic::Length '''unitAmount:'''10000000) '''printString''' => 10000 km
(Physic::Length '''meter''' '''unitAmount:'''10000000) '''printString''' => 10000000 m

In addition, physical value instances can be converted to their corresponding SI base unit value via "asBaseUnitValue". And of course, values in base units will return themself. For example:
(Physic::Length '''unitAmount:'''2) '''asBaseUnitValue''' => 2 m
(Physic::Length '''feet''' '''unitAmount:'''2) '''asBaseUnitValue''' => 0.6096 m
(Physic::Length '''meter''' '''unitAmount:'''10000000) '''asBaseUnitValue''' => 10000 km

More on this below in the physical values chapter.

=== Number Prefix Messages===

==== SI Prefix ====

[[Number_API_Functions|Numbers]] (in Smalltalk and JavaScript) can be scaled by an SI prefix message.
Thus, when combining a unit message with a scaled number, we get a scaled physical value.
 For example, without SI prefix, we get:
1 '''gram''' => '1 g'
whereas with a 'micro' prefix, the result is:
1 '''micro''' '''gram''' => '1 µg'
or:
1 '''hecto''' '''liter''' => '100 liter'

The corresponding JavaScript code is similar, but slightly less elegant looking due to the required periods and parentheses:
1.'''gram'''()
1.'''micro'''().'''gram'''()
1.'''hecto'''().'''liter'''()

Possible scaling prefixes are:
yocto 1E-24 1 / 1000000000000000000000000
zepto 1E-21 1 / 1000000000000000000000
atto 1E-18 1 / 1000000000000000000
femto 1E-15 1 / 1000000000000000
pico 1E-12 1 / 1000000000000
nano 1E-9 1 / 1000000000
micro 1E-6 1 / 1000000
milli 1E-3 1 / 1000
centi 1E-2 1 / 100
deci 1E-1 1 / 10
deca 1E+1 10
hecto 1E+2 100
kilo 1E+3 1000
mega 1E+6 1000000
giga 1E+9 1000000000
tera 1E+12 1000000000000
peta 1E+15 1000000000000000
exa 1E+18 1000000000000000000
zetta 1E+21 1000000000000000000000
yotta 1E+24 1000000000000000000000000
ronna 1E+27 1000000000000000000000000000
quetta 1E+30 1000000000000000000000000000000

You can combine the SI scale with a unit, as in:
1 '''kilo''' '''meter'''
1 '''micro''' '''ampere'''
1 '''mega''' '''watt'''
1 '''pico''' '''farad'''
1 '''exa''' '''bytes'''

For some common units, additional shortcuts exist:
1 kiloMeter ; centiMeter ; milliMeter ; microMeter ; nanoMeter
1 milliGram ; microGram
1 kiloAmpere ; milliAmpere ; microAmpere ; nanoAmpere
1 kiloVolt ; milliVolt ; microVolt
1 kiloByte ; megaByte ; teraByte ; peraByte ; exaByte
1 kiloJoule ; megaJoule
1 kiloHertz ; megaHertz ; gigaHertz
1 kiloOhm ; megaOhm
1 kiloWatt ; teraWatt ; gigaWatt ; megaWatt ; milliWatt

But in general, you will have to combine the SI scale with a unit as described above.

==== Bits & Bytes ====
In addition to the above listed powers-of-10 scaling prefixes,
there are also powers-of-2 prefixes, which are usually only used with byte or bit amounts.

kibi 2ˆ10 1024
mebi 2ˆ20 1048576 (same as "1024 * 1024" or "1024 kibi")
gibi 2ˆ30 1073741824 (same as "1024 * 1024 * 1024" or "1024 mebi)
tebi 2ˆ40 1099511627776
pebi 2ˆ50 1125899906842624
exbi 2ˆ60 1152921504606846976
zebi 2ˆ70 1180591620717411303424
yobi 2ˆ80 1208925819614629174706176

For the kibi scaler, you can use the shortcut:
1 '''kibiByte''' => 1024 B
all others need to be combined, as in:
1.0 '''mebi''' '''byte''' => 1024 kiB
1.0 '''mebi''' '''byte''' '''asMegaBytes''' => 1.048576 MB
1.0 '''mebi''' '''byte''' '''asMebiBytes''' => 1 MiB
1.0 '''mebi''' '''bits''' => 1048.576 kbit
1.0 '''mebi''' '''bits''' '''asMegaBytes''' => 0.131072 MB
1.0 '''mebi''' '''bits''' '''asMebiBytes''' => 0.125 MiB

==== Hundreds, thousands etc. ====
In addition, the prefixes "hundred", "thousand" and "million" are supported:
1 '''hundred''' '''million''' '''kilo''' '''gram''' =>100000000 kg
To represent the pressure inside the sun, write:
26.5 '''million''' '''giga''' '''pascal''' => 2.65e+16 Pa
or
26.5 '''million''' '''giga''' '''pascal''' '''asPSI''' => 3843364757070.34 psi
There is intentionally NO SUPPORT for billion, trillion etc., because most german journalists and even some non journalists have no idea about US vs. continental meanings of those (big smiley here). In britain, its even worse, where both systems are used in parallel (https://de.wikipedia.org/wiki/Billion).

==== Imperial / American / Metric Prefix ====
For some units, additional prefixes are allowed.

american / imperial:
barrel, cup, floz, gallon, pint, quart, tablespoon, teaspoon
dry pint, dry quart, dry peck
metric / imperial:
ton, hp

I.e. you can write:
1 imperial gallon => 4.54609 l
1 american gallon => 3.785411784 l
1 metric ton => 1000 kg
1 imperial ton => 1016.0469088 kg
1 imperial teaspoon => 5.91939880031792 ml
1 american pint => 473.176473 ml
1 american dry pint => 550.6104713575 ml

==== Square / Cubic Prefix ====
For readability, there are also a square and cubic prefíxes, usable with: centiMeter. feet, inches, kiloMeter, meter, miles, milliMeter, yards.

You can write:
1 square meter => 1 m²
1 cubic feet => 28.316846592 l
1 square yard => 0.83612736 m²

==== Troy Prefix ====
For readability, there is also a troy prefíx, usable only with ounces.

You can write:
1 troy ounce => 31.1034768 g
1 american ounce => 28.349523125 g
1 british ounce => 28.349523125 g

== Unit API ==

==== Units vs. Values ====
Internally, PhysicalValues are represented as a pair of a PhysicalUnit and an amount. PhysicalUnit may be either one of the above listed base units (i.e. SI base units), or a scaling/converting unit (e.g. Inches or Hectare but also MilliMeter). The amount is always the baseUnit amount i.e. meter, kilogram, square meter etc.

===== Units =====
You can get a unit (in contrast to a value) by sending one of the unit-messages to the Physic::PhysicalUnit class (i.e. the class named "''PhysicalUnit''" in the "''Physic''" namespace).

For example,
Physic::PhysicalUnit energy
will give you the "Energy" class which represents values in "Joule".

Conversion units are retrieved by asking one such unit for another unit, by sending it a corresponding getter message.

For example, we can ask the Energy class for a converting class named "Calories" or "KiloCalories" with:
Physic::PhysicalUnit energy calories
Physic::PhysicalUnit energy kilo calories

Actually, you can also ask the (abstract) PhysicalUnit class for a unit:
Physic::PhysicalUnit calories
Physic::PhysicalUnit kilo calories

===== Values =====
On the basic level, PhysicalValue are created by sending the "<CODE>unitAmount:</CODE>" or "<code>baseUnitAmount:</code> message to a unit. However, for the most common units, convenient and more readable messages are implemented in the [[Number_API_Functions|Number]] hierarchy. These allow for shorter code and will be described below.
 For example:
Physic::PhysicalUnit energy unitAmount:100
=> 100 J
generates an energy instance of 100 joule.

The argument of the "<CODE>unitAmount:</CODE>" call is always given in units of the receiver unit, whereas the alternative constructor named "<CODE>baseUnitAmount:</CODE>" expects the argument to be in the underlying base unit (i.e. one of the SI units).

This makes no difference for the base SI units, but is relevant, if you deal with conversion units (e.g. imperial units) as described later.
 Thus,
Physic::PhysicalUnit energy calories unitAmount:100
=> 100 cal
Physic::PhysicalUnit calories unitAmount:100
=> 100 cal
will create an energy instances of 100 calories (which will print themself as 100 calories),
 whereas:
Physic::PhysicalUnit energy calories baseUnitAmount:100
=> 23.9005736137667 cal
will create an energy instance of 100 joule (but it will print itself as 23.90 calories).

Notice, that the "<code>energy</code>" message is a facade getter method of Physic::PhysicalUnit. It retrieves the Energy class, which is actually named "Physic::Energy" and is also located in the Physic namespace.
 So we could have written:
Physic::Energy calories unitAmount:100
=> 100 cal
or, given 100 joule:
Physic::Energy calories baseUnitAmount:100
=> 23.9005736137667 cal

====== Value Creation ======

Given one of the units as listed below, a value instance can be created by different ways:

 Given an amount in that unit, as in:
Physic::Mass kilogram unitAmount:1.5.
=> 1.5 kg

Physic::Mass troyOunces unitAmount:1.5.
=> 1.5 oz t

Given an amount in base SI units (same as unitAmount for the SI units, but different for derived units):
Physic::Mass kilogram baseUnitAmount:1.5.
=> 1.5 kg

Physic::Mass troyOunces baseUnitAmount:1.5.
=> 48.226119852942 oz t. (i.e. 1.5kg as troy ounces)

By converting, given a value in any unit and a target unit:
(Physic::Mass kilogram unitAmount:0.1) as:(Physic::Mass troyOunces)
=> 3.2150746568628 oz t. (i.e. 0.1 kg as troy ounces)

same, but given a target unit's name:
(Physic::Mass kilogram unitAmount:0.1) as:'Pounds'
=> 0.220462262184878 lb.

or given a target unit's unitString:
(Physic::Mass kilogram unitAmount:0.1) as:'lb'
=> 0.220462262184878 lb.

==== SI Base and Derived Units ====
Getters for well known units are:

Physic::PhysicalUnit acceleration
Physic::PhysicalUnit amountOfSubstance
Physic::PhysicalUnit angle
Physic::PhysicalUnit area
Physic::PhysicalUnit currentDensity
Physic::PhysicalUnit electricCapacitance
Physic::PhysicalUnit electricCharge
Physic::PhysicalUnit electricConductance
Physic::PhysicalUnit electricCurrent
Physic::PhysicalUnit electricResistance
Physic::PhysicalUnit energy
Physic::PhysicalUnit force
Physic::PhysicalUnit frequency
Physic::PhysicalUnit inductance
Physic::PhysicalUnit length
Physic::PhysicalUnit luminousIntensity
Physic::PhysicalUnit mass
Physic::PhysicalUnit massDensity
Physic::PhysicalUnit power
Physic::PhysicalUnit pressure
Physic::PhysicalUnit specificVolume
Physic::PhysicalUnit temperature
Physic::PhysicalUnit time
Physic::PhysicalUnit velocity
Physic::PhysicalUnit voltage
Physic::PhysicalUnit volume

Physic::PhysicalUnit knownUnits

The last returns a collection of all known units (there are actually more than listed above).

The very most used units are directly accessible via a global under the Physic namespace:
Physic::Mass
Physic::Length
Physic::Energy
Physic::Velocity
etc.

For common units, additional instance creation protocol is provided in the [[Number_API_Functions|Number]] class. E.g.:
100 joule => 100 J
will generate the same as:
(Physic::PhysicalUnit energy) baseUnitAmount:100 => 100 J
which is the same as:
Physic::Energy baseUnitAmount:100 => 100 J
which (for base units) is the same as:
Physic::Energy unitAmount:100 => 100 J
The additional [[Number_API_Functions|Number]]-protocol is described below.

In the above examples, the unit was a baseUnit, and therefore the baseUnitAmoun the same as the unitAmount.

Things are different for derived units:
Physic::Energy calories unitAmount:100 => 100 cal
vs.
Physic::Energy calories baseUnitAmount:100 => 23.9005736137667 cal (because these are 100 joule)
More on that below.

==== Printing Unit Values ====
When printed, physical values will scale and use an SI prefix as appropriate. For example, by default, a value of 10 millimeter will print as "10 mm" instead of "0.01 m" (remember: meter is the underlying SI base unit). The choice of prefix (milli, micro, nano, etc.) is decided by the unit's "printWithUnit:on:" method, which in case of length values chooses an appropriate prefix from nanos to lightyears, based on heuristics.

This print behavior can be changed by converting to an explicit converting unit via one of the "<CODE>asXXX</CODE>" messages listed below. However, the SI base unit amount will be kept internally and used in arithmetic operations. Thus, e.g. when adding a meter with inches, an SI meter value will be generated, and the result will be presented in the same unit as the receiver (first operand). For example:
1 inch
returns an SI base-unit value (i.e. in meters) and will print as meter (actually as '25.4 mm'), whereas:
1 inch asInches
will print itself as inches because of the "asInches" message.
 All of:
1 meter + 1 inch
1 meter + 1 inch asInches
1 inch + 1 meter
will print as meter ('1.0254 m'), because the first operand's unit determines the unitString.
 However,
1 inch asInches + 1 meter
1 inch asInches + 1 meter asInches
will all print as inches ('40.37 in').

You can also pass a target unit string, as in:
1 meter as:'in'
or the target unit:
1 meter as:(Physic::Length inches)
or the unit's name:
1 meter as:'Inches'
which all print as '39.3700787401575 in'.

==== Printing with another Unitstring ====
Some units are printed with different unit symbols, depending on context.
 For example, nautical miles are printed in aviation as "NM", whereas in US official documents they are printed as "nmi". And a german document might want to print them as "sm" ("Seemeilen").

For that, convert the value (or unit) with "<code>withUnitSymbol:</code>".
 For example, a value of two nauticalMiles is printed in different units:
2 nauticalMiles printString
=> '3704 m'
2 nauticalMiles asNauticalMiles printString
=> '2 NM'
(2 nauticalMiles asNauticalMiles withUnitSymbol:'nmi') printString
=> '2 nmi'
(2 nauticalMiles asNauticalMiles withUnitSymbol:'sm') printString
=> '2 sm'

Applying the above message to a unit (instead of a value) gives a new unit.
 For example, a bottle unit, which corresponds to 0.7 lters:
bottleUnit := Physic::Volume liter withUnitSymbol:'bottle' scaleFactor:0.7.

can create bottle-values:
(bottleUnit unitAmount:10)
=> 10 bottle

or convert from liters:
10 liter as:bottleUnit
=> 14.286 bottle

===== Printing in Another Language =====
The same scheme can be used to print values with national translations of a unit.
For example, tons of coal equivalents ('toe') is "Tonnen Steinkohle Äquivalent" or tSKE in German. Reasonable definitions could be:
toeGerman := Physic::Energy toe withUnitSymbol:'tSKE' scaleFactor:1.
mtoeGerman := toeGerman megaUnit.
so the mtoeGerman unit will represent megatons of coal equivalents and print its values with a 'MtSKE' unit (see scaling units below):
mtoeGerman unitAmount:100
=> 100 MtSKE
and
(mtoeGerman unitAmount:100) asGigaJoules
=> 4186800000 GJ
or:
(mtoeGerman unitAmount:100) as:'PJ'
=> 4186.8 PJ

Similar:
meterChinese := Physic::Length withUnitSymbol:'米 (Mǐ)' scaleFactor:1.
meterChinese unitAmount:15
=> 15 米 (Mǐ)

==== Converting Units ====

In addition to predefined converting units, as listed below,
it is also possible to define custom units, with different (customizable) print behavior (more on that below).

==== Predefined Converting Units ====

Some such custom units are already predefined; for example, to represent imperial units, conversion units derived from mass are found (among others) as:
Physic::PhysicalUnit mass ounces (or Physic::Mass ounces)
Physic::PhysicalUnit mass pounds (or Physic::Mass pounds)
and length units as:
Physic::PhysicalUnit length inches (or Physic::Length inches)
Physic::PhysicalUnit length feet
Physic::PhysicalUnit length yards

Thus, you can create unit values which print themself (e.g.) in imperial units:
yardsUnit := Physic::Length yards.
distance := yardsUnit unitAmount:10
will give you 10 yards, which prints itself as such ('10 yd').

Whereas:
distance2 := yardsUnit baseUnitAmount:10
will create a distance of 10 meters (the underlying base unit), which prints itself in yards.

Be careful to not confuse ''unit amounts'' with ''base unit amounts'',
and be reminded that the internal storage representation of all units is always in SI base units. The conversion is only performed when such values are printed.

In general, you can ask most base units for common conversion units (which are the units used by the asXXX converters below).
These can also be used to instantiate instances or for conversion.
E.g.
Physic::Mass ounces unitAmount:1
returns 1 ounce (which prints itself as such),
and:
1 kiloGram as:(Physic::Mass ounces)
returns 32.27 ounces (which also prints itself as such).

==== Predefined Scaling Units ====
By default, the unit chooses itself, how values are scaled when printing.
For example, "(1/1000.0) kilo gram" will print itself as "1 g", although the underlying baseUnit is kilogram.

You can force a particular scale either by using one of the scale-converting units, eg:
''someUnit'' asMilliUnit baseUnitAmount:''scalarValueInBaseUnits''
or by giving it a unit amount:
''someUnit'' asMilliUnit unitAmount:''scalarValueInUnits''
or by converting a unit-value:
''someUnitValue'' asMilliUnitValue
Again, ''scalarValueInBaseUnits'' is in base-units (kg, N, Hz,...), whereas ''scalarValueInUnits'' is in scaled-units (mg, kN, Mhz,...).

For example:
0.01 kilo gram
=> prints as "10 g"

Physic::Mass baseUnitAmount:0.01
=> prints as "10 g"

Physic::Mass milliUnit baseUnitAmount:0.01 "/ specified in kg here
=> prints as "10000 mg"

Physic::Mass milliUnit unitAmount:100 "/ specified in mg here
=> prints as "100 mg"

To get a scaling unit from a given base unit (such as "Mass", "Length", "Volume", etc.)
or from a given derived Unit (such as "Volume liters"), apply one of the following:
''aUnit'' picoUnit
''aUnit'' nanoUnit
''aUnit'' microUnit
''aUnit'' milliUnit
''aUnit'' centiUnit
''aUnit'' deciUnit
''aUnit'' hectoUnit
''aUnit'' kiloUnit
''aUnit'' megaUnit
''aUnit'' gigaUnit
''aUnit'' teraUnit
''aUnit'' petaUnit
''aUnit'' exaUnit

For example, if you have to work with hectoliters (units of 100 liters), which is common in europe's farming, make yourself a corresponding unit with:
hlUnit := Physic::Volume liters hectoUnit.
wine := hlUnit unitAmount:15.0.
wine printString
=> 15 hl"
wine asCubicMeters printString
=> 1.5 m³"
wine asLiters printString
=> 1500 l
wine asGallonsUS printString
=> 396.258078537223 US gal
(wine asGallonsUS roundTo:0.01) printString
=> 396.26 US gal

To convert a given value (as opposed to a unit as above), use one of:

''aValue'' asPicoUnitValue
''aValue'' asNanoUnitValue
''aValue'' asMicroUnitValue
''aValue'' asMilliUnitValue
''aValue'' asCentiUnitValue
''aValue'' asDeciUnitValue
''aValue'' asHectoUnitValue
''aValue'' asKiloUnitValue
''aValue'' asMegaUnitValue
''aValue'' asGigaUnitValue
''aValue'' asTeraUnitValue
''aValue'' asPetaUnitValue
''aValue'' asExaUnitValue

therefore, to force a physical value to print itself in its 'milli' unit,
use asMilliUnitValue, as in:
i := 1 ampere.
m_i := i asMilliUnitValue.

The asXXXUnitValue methods work on any physical value,

However, you can also and should use the unit-specific converters, here:
m_i := i asMilliAmperes
or with masses, as in the above example:
0.01 kilo gram asMilliUnitValue
0.01 kilo gram asMilliGrams

The unit-specific methods will only work on their specific unit values (meaning that you get an error when trying to ask any non-mass value for its milligrams).
Thus, the later are preferable, as they provide an additional quality check
for your code. For a list of unit-specific converters, see below.

==== Predefined Wellknown Units ====

The base SI units Mass, Length, Force, etc. can be directly accessed from the Physic namespace as <code>Physic::<nameOfUnit></code>.

Other derived and less frequently units can be accessed either via getters from the Physic::PhysicalUnit class, or by asking it via <code>Physic::PhysicalUnit unitNamed:'nameOfUnit'</code>.
 A list of known basic and derived SI units is retrieved with <code>Physic::PhysicalUnit knownUnits</code>.

For details, see [https://en.wikipedia.org/wiki/United_States_customary_units US Units],
[https://en.wikipedia.org/wiki/Centimetre%E2%80%93gram%E2%80%93second_system_of_units CGS System], [https://en.wikipedia.org/wiki/Avoirdupois Avoirdupois] and [https://en.wikipedia.org/wiki/International_System_of_Units SI Units].

====== Acceleration Unit ======
*Physic::Acceleration
::The base unit is "m/s²".
*Physic::Acceleration '''gForce'''
::Returns the "GForce" converting unit (i.e. units o earth's gravitation).

====== AmountOfSubstance Unit ======
*Physic::AmountOfSubstance
::The base unit is "mol".
*Physic::AmountOfSubstance '''particles'''
::Returns the (number of) "Particles" converting unit.

====== Angle Unit ======
*Physic::Angle
::The base SI unit. Prints as "rad".
*Physic::Angle '''degrees'''
::Returns the "Degrees" converting unit. Prints its values in degrees.
*Physic::Angle '''degreeAndMinAndSec'''
::Returns a converting unit which prints its values in integer degrees plus minutes (1/60s degrees) plus seconds (1/3600s degrees).
*Physic::Angle '''gon'''
::Returns the "Gon" converting unit.
*Physic::Angle '''radians'''
::Returns the "Radians" converting unit.
*Physic::Angle '''arcMin'''
::Returns the "ArcMinutes" converting unit.
*Physic::Angle '''arcSec'''
::Returns the "ArcSeconds" converting unit.
*Physic::Angle '''arcMinAndSec'''
::Returns the "ArcMinutesAndSeconds" converting unit.

====== Area Unit ======
*Physic::Area
::The base SI unit. Prints as square meters.
*Physic::Area '''acre'''
::converting unit which prints as acres.
*Physic::Area '''are'''
::Prints as ares.
*Physic::Area '''awg'''
::converting unit which prints as American Wire Gauge.
*Physic::Area '''hectare'''
::Prints as hectares (ha).
*Physic::Area '''squareFoot'''
::Prints as square feet (sq ft).
*Physic::Area '''squareMiles'''
::Prints as square miles (sq mi).
*Physic::Area '''squareMillimeterMeters'''
::Prints as square millimeters (mm2).
*Physic::Area '''squareCentiMeters'''
::Prints as square centimeters (cm2).
*Physic::Area '''squareMeters'''
::Prints as square meters (m2).
*Physic::Area '''squareKiloMeters'''
::Prints as square kilometers (km2).

====== Bits & Bytes Units ======
*Physic::Bytes
::The bytes unit. Not really an SI unit, but useful for printing file sizes.
*Physic::Bytes '''kiloBytes'''
::a converting unit; prints as "kB".
*Physic::Bytes '''megaBytes''' / '''gigaBytes''' / '''teraBytes''' etc.
::converting units; print as "MB", "GB", "TB", etc.
*Physic::Bytes '''kibiBytes''' / '''mebiBytes''' / '''gibiBytes''' / '''tebiBytes''' etc.
::converting units; print as "kiB", "MiB", "GiB", "TiB", etc.
*Physic::Bits
::The bits unit. Not really an SI unit, but useful for printing transmission speeds (bits/s).
*Physic::Bits '''kiloBits'''
::a converting unit; prints as "kbit".
*Physic::Bits '''megaBits''' / '''gigaBits''' / '''teraBits''' etc.
::converting units; print as "Mbit", "Gbit", "Tbit", etc.
*Physic::Bits '''kibiBits''' / '''mebiBits''' / '''gibiBits''' / '''tebiBits''' etc.
::converting units; print as "kibit", "Mibit", "Gibit", "Tibit", etc.

====== Electric Charge Unit ======
*Physic::ElectricCharge
::The base SI unit. Prints as coulomb ("C").
*Physic::ElectricCharge '''ampereSeconds'''
::a converting unit which prints as "As".
*Physic::ElectricCharge '''ampereHours'''
::a converting unit which prints as "Ah".
*Physic::ElectricCharge '''elementaryCharges'''
::a converting unit which prints as number of elementary charges "q".

====== Electric Current Unit ======
*Physic::ElectricCurrent
::The base SI unit. Prints as ampere ("A").

====== Electric Resistance Unit ======
*Physic::ElectricResistance
::The base SI unit. Prints as ohm.

====== Energy Unit ======
*Physic::Energy
::The base SI unit. Prints as joules ("J").
*Physic::Energy '''wattHours'''
::a converting unit which prints as "Wh"
*Physic::Energy '''kiloWattHours'''
::a converting unit which prints as "kWh"
*Physic::Energy '''megaWattHours'''
::a converting unit which prints as "MWh"
*Physic::Energy '''gigaWattHours'''
::a converting unit which prints as "GWh"
*Physic::Energy '''kiloJoules'''
::a converting unit which prints as "kJ"; same as "Energy kiloUnit"
*Physic::Energy '''megaJoules'''
::a converting unit which prints as "MJ"; same as "Energy megaUnit"
*Physic::Energy '''gigaJoules'''
::a converting unit which prints as "GJ"; same as "Energy gigaUnit"
*Physic::Energy '''btu'''
::a converting unit which prints as "btu" (British Thermal Units), 1055 J based on the ISO 31-4 definition
*Physic::Energy '''boe'''
::a converting unit which prints as "boe" (Barrels of Oil Equivalent, 6117.9 MJ based on the US Internal Revenue Service)
*Physic::Energy '''toe'''
::a converting unit which prints as "toe" (Tons of Oil Equivalent), 41.9 GJ
*Physic::Energy '''tce'''
::a converting unit which prints as "tce" (Tons of Coal Equivalent), 29 GJ
*Physic::Energy '''calories'''
::a converting unit which prints as "cal"
*Physic::Energy '''kiloCalories'''
::a converting unit which prints as "kcal"
*Physic::Energy '''electronVolts'''
::a converting unit which prints as "eV"
*Physic::Energy '''kiloElectronVolts'''; same as "Energy electronVolts kiloUnit".
::a converting unit which prints as "keV"
*Physic::Energy '''erg'''
::a converting unit which prints as "erg"

====== Force Unit ======
*Physic::Force
::The base SI unit. Prints as Newton.
:converting units are returned by: '''dyne''', '''gramForce''', '''newtons''', '''poundForce''', '''tonForce'''

====== Frequency Unit ======
*Physic::Frequency
::The base SI unit. Prints as Hertz.
:converting units are returned by: '''hertz''', '''kiloHertz''', '''megaHetz''', '''gigaHertz''', '''rpm'''.

====== Length Unit ======
*Physic::Length
::The base SI unit. Prints as Meter with a reasonable scale prefix.
*Physic::Length '''centiMeters'''
::a converting unit which prints as "cm".
*Physic::Length '''milliMeters'''
::a converting unit which prints as "mm".
*Physic::Length '''microMeters'''
::a converting unit which prints as "µm".
*Physic::Length '''nanoMeters'''
::a converting unit which prints as "nm".
*Physic::Length '''meters'''
::a converting unit which always prints as "m".
*Physic::Length '''kiloMeters'''
::a converting unit which prints as "km".
*Physic::Length '''inches'''
::a converting unit which prints as "in".
*Physic::Length '''feet'''
::a converting unit which prints as "ft".
*Physic::Length '''feetAndInches'''
::a converting unit which prints feet and inches.
*Physic::Length '''feetAndInchesRounded'''
::a converting unit which prints feet and rounded inches; a typical format used in the US for a human's height
*Physic::Length '''metersAndCentimeters'''
::a converting unit which prints meter and rounded centimeters; a useful format a human's metric height
*Physic::Length '''yards'''
::a converting unit which prints as "yd".
:additional converting units are returned by: '''angstrom''', '''astronomicalUnits''', '''parsec''', '''awgDiameter''', '''landMiles''', '''lightSeconds''', '''lightYears''', '''meters''', '''nauticalMiles''', '''thous''', '''mils''', '''points''', '''twips'''.

====== Mass Unit ======
*Physic::Mass
::The base unit ("kg").
*Physic::Mass '''ounces'''
::Returns the "Ounces" unit; a converting unit which prints as "oz".
*Physic::Mass '''pounds'''
::Returns the "Pounds" converting unit which prints as "lb".
*Physic::Mass '''troyOunces'''
::Returns the "TroyOunces" converting unit.
*Physic::Mass '''carat'''
::Returns the "Carat" converting unit.
*Physic::Mass '''atomicMassUnits'''
::Returns the "AtomicMassUnits" converting unit.
:more mass converting units are returned by: '''daltons''', '''grams''', '''kiloGrams''', '''kiloTonnes''', '''megaTonnes''', '''milliGrams''', '''microGrams''', '''nanoGrams''', '''tonnes''', '''troyPounds'''.

You may wonder what the kiloGrams converting unit is useful for, as the base unit's amount is already in kilograms. The difference is that the base unit will print values with a prefix (milli, micro, kilo etc.) whereas the kiloGram converting unit will always print kilograms.

====== Power Unit ======
*Physic::Power
::The base SI unit. Prints as Watt.
:converting units are returned by: '''dBW''', '''dBm''', '''gigaWatt''', '''kiloWatt''', '''megaWatt''', '''milliWatt'''

====== Pressure Unit ======
*Physic::Pressure
::The base SI unit. Prints as Pascal.
:converting units are returned by: '''atmospheres''', '''technicalAtmospheres''', '''bar''', '''hectoPascal''', '''mH2O''' (meter of water), '''mmHg''' (mm of mercury), '''pascal''', '''psi''' and '''torr'''.

====== Temperature Unit ======
*Physic::Temperature
::The base SI unit. Prints as Kelvin.
:converting units are returned by: '''celsius''', '''fahrenheit''', '''rankine'''

====== Time Unit ======
:Time durations are either represented by the already existing standard Smalltalk class "TimeDuration" or by the Time unit in the Physic namespace. Mixed arithmetic operations involving TimeDurations and PhysicalValues are transparently returning correct unit values. However, TimeDuration has a limitation in that it can only represent times down to the picosecond range, which might be not enough for high energy physic computations. Please use Physic::Time in this case.
*Physic::Time
::The base SI unit. Prints as Seconds.
:converting units are returned by: '''days''', '''microSeconds''', '''milliSeconds''', '''seconds''', '''weeks''', '''years'''

====== Velocity Unit ======
*Physic::Velocity
::The base SI unit. Prints as Meter per Second.
:converting units are returned by: '''beaufort''', '''centiMetersPerSecond''', '''kiloMetersPerHour''', '''kiloMetersPerSecond''', '''knots''', '''metersPerHour''', '''milesPerHour'''

====== Voltage Unit ======
*Physic::Voltage
::The base SI unit. Prints as Volts.
:converting units are returned by: '''milliVolts''', '''microVolts''', '''nanoVolts''', '''kiloVolts''', '''dBV''', '''dBu'''

====== Volume Unit ======
*Physic::Volume
::The base SI unit. Prints as Cubic Meter.
:converting units are returned by: '''centiLiters''', '''cubicInches''', '''cubicMeters''', '''deciLiters''', '''fluidOuncesGB''', '''fluidOuncesUS''', '''gallonsGB''', '''gallonsUS''', '''hectoLiters''', '''liters''', '''milliLiters''', '''barrels''', '''barrelsIMP''', '''barrelsUS''' (barrels are oil aka "blue barrels")

== Per Unit Detailed API ==

Notice the receiver of expressions in the following per-unit documentation.
 If you read "''number'' '''something'''", it means that you can send any [[Number_API_Functions|number]] instance the "something" message.
 And you will get an instance of the corresponding unit value as result.
For example:
2 gram
or
3.0 gram
or
(1/2) kiloGram
will all return corresponding mass value.

If you read "''aMass'' '''something'''", it means that you can send the "something" message to a unit value instance (eg. a mass)
and get some other representation of it as result.

Finally, if you read "''aUnit'' '''something'''", it means that you can send the "something" message to a physical unit (not a physical value).

=== Mass ===

Mass is measured in units of Kilogram, and the default printing is in "kg", "g", "mg", "ng" or whatever the print function considers appropriate.
 The following operations return an instance of a mass (i.e. a value with a unit of "Mass") all of which will print themself as base units:

'''Instance Creation'''
*''aNumber'' '''kiloGram''' ''aNumber'' '''kilo''' '''gram'''
::Generates a mass-value of n kilograms. Same as <CODE>n kilo gram</CODE> (using SI prefix message).

*''aNumber'' '''gram'''
::Generates a mass-value of n grams.

*''aNumber'' '''milliGram''' ''aNumber'' '''milli''' '''gram'''
::Generates a mass-value of n milligrams. Same as <CODE>n milli gram</CODE>. (using SI prefix message)

*''aNumber'' '''microGram''' ''aNumber'' '''micro''' '''gram'''
::Generates a mass-value of n micrograms. Same as <CODE>n micro gram</CODE> (using SI prefix message).

*''aNumber'' '''nano''' '''gram'''
::All SI prefixes as listed above.

*''aNumber'' '''pounds'''
::Generates a mass-value of n pounds. A pound is defined as 453.59237 gram.

*''aNumber'' '''ounces'''
::Generates a mass-value of n ounces. An ounce is defined as 28.35 g.

*''aNumber'' '''troyOunces'''
*''aNumber'' '''troy ounces'''
::Generates a mass-value of n troy ounces. These are used with metals (esp. gold) (31.1034768 g)

*''aNumber'' '''imperial''' '''ton'''
::Generates a mass-value of 1016.05 kg (2240 lb)
::Also possible: '''imperial''' '''barrel''', '''bushel''', '''cup''', '''floz''', '''fluidOunce''', '''gallon''', '''hp''', '''nauticalMile''', '''pint''', '''quart''', '''tablespoon''', '''teaspoon''', '''ton'''

*''aNumber'' '''american''' '''ton'''
::Generates a mass-value of 907.2 kg (2000 lb)
::Also possible: '''american''' '''barrel''', '''bushel''', '''cup''', '''fldr''', '''fluidDram''', '''floz''', '''fluidOunce''', '''gallon''', '''hp''', '''nauticalMile''', '''pint''', '''quart''', '''tablespoon''', '''teaspoon''', '''ton'''

*''aNumber'' '''metric''' '''ton'''
::Generates a mass-value of 1000 kg (2204 lb)
::Also possible: '''metric''' '''hp''', '''pint''', '''ton'''

'''Unit Conversion'''

*''aMass'' '''asGrams'''
::Returns the original mass in a converted unit which enforces explicit printing in grams (i.e. without any SI scaling prefix).

*''aMass'' '''asNanoGrams'''
::Same, but enforces explicit printing in nanograms ("ng").

*''aMass'' '''asMicroGrams'''
::Enforces explicit printing in micrograms ("µg").

*''aMass'' '''asMilliGrams'''
::Enforces explicit printing in milligrams ("mg").

*''aMass'' '''asKiloGrams'''
::Enforces explicit printing in kilograms ("kg").

*''aMass'' '''asTonnes'''
::Enforces explicit printing in (metric) tonnes ("t").

*''aMass'' '''asKiloTonnes'''
::Enforces explicit printing in (metric) kilotonnes ("kt").

*''aMass'' '''asMegaTonnes'''
::Enforces explicit printing in (metric) megatonnes ("Mt").

*''aMass'' '''asGigaTonnes'''
::Enforces explicit printing in (metric) gigatonnes ("Gt").

*''aMass'' '''asPounds'''
::Enforces explicit printing in pounds ("lb") One pound is 453.59237 g.

*''aMass'' '''asCarat'''
::Enforces explicit printing in carat ("ct"). 1 carat is 200mg.

*''aMass'' '''asOunces'''
::Enforces explicit printing in ounces ("oz"). These are british (imperial) ounces (28.35 g)

*''aMass'' '''asTroyOunces'''
::Enforces explicit printing in troy ounces ("oz t"). These are used with metals (31.103 g)

*''aMass'' '''asDaltons'''
::Enforces explicit printing in dalton ("Da"). 1 dalton is 1/12 of the C12 atom's mass (1.66053906892e-27 kiloGram).

*''aMass'' '''asAtomicMassUnits'''
::Enforces explicit printing in atomic mass units ("amu"). One amu is 1.660539066605e-27Kg.

'''In a Formula''' ('...' asPhysicExpression value)
*<code>'100 kg'</code>
::mass in Kilogram. Also recognized: 'mg', 'µg', 'ng', 't'

*<code>'100 lb'</code>
::mass in pounds. Also recognized: 'oz', 'oz tr', 'us ton', 'imp ton'

=== Length ===
Length is measured in Meters, and the default printing is in "m", "km", "mm", "nm" or whatever the print function considers appropriate.

'''Instance Creation'''
*''aNumber'' '''meter'''
::Generates a length-value of n meters.

*''aNumber'' '''centiMeter''' ''aNumber'' '''centi''' '''meter'''
::Generates a length-value of n centimeters. Same as <CODE>n centi meter</CODE>.

*''aNumber'' '''milliMeter''' ''aNumber'' '''milli''' '''meter'''
::Generates a length-value of n millimeters. Same as <CODE>n milli meter</CODE>.

*''aNumber'' '''microMeter''' ''aNumber'' '''micro''' '''meter'''
::Generates a length-value of n micrometers. Same as <CODE>n micro meter</CODE>.

*''aNumber'' '''nanoMeter''' ''aNumber'' '''nano''' '''meter'''
::Generates a length-value of n nanometers. Same as <CODE>n nano meter</CODE>.

*''aNumber'' '''kiloMeter''' ''aNumber'' '''kilo''' '''meter'''
::Generates a length-value of n kilometers. Same as <CODE>n kilo meter</CODE>.

*''aNumber'' '''inch'''
::Generates a length-value of n inches. An inch is 25.4 mm.

*''aNumber'' '''inches'''
::Same as inch above (for readability)

*''aNumber'' '''feet'''
::Generates a length-value of n feet. A foot is 12 inches or 0.3048 m.

*''aNumber'' '''yards'''
::Generates a length-value of n yards. A yard is 36 inches or 0.9144 m.

*''aNumber'' '''landMiles'''
::Generates a length-value of n land miles. A land mile is 5280 feet or 1609.344 m.

*''aNumber'' '''nauticalMiles'''
::Generates a length-value of n nautical miles. A nautical mile is 1852 m (i.e. a US nautical mile, not to be confused with the obsolete british nautical mile, which is slightly longer).

*''aNumber'' '''chineseMiles'''
::Generates a length-value of n chinese miles. A Chinese mile is 500 m.

*''aNumber'' '''astronomicalUnits'''
::Generates a length-value of n [https://en.wikipedia.org/wiki/Astronomical_unit astronomical units]. An au is 149597870.7 km.

*''aNumber'' '''lightSeconds'''
::Generates a length-value of n lightseconds. A ls is 299792.458 km.

*''aNumber'' '''lightYears'''
::Generates a length-value of n [https://en.wikipedia.org/wiki/Light-year lightyears]. A ly is 9460730472580.8 km (exact by definition).

*''aNumber'' '''parsec'''
::Generates a length-value of n [https://en.wikipedia.org/wiki/Parsec parsec]. A parsec is 3.26156377716705 ly.

*''aNumber'' '''angstrom'''
::Generates a length-value of n angstroms. 1 Å = 0.1 nm = 10e−10 m.

'''Unit Conversion'''

*''aLength'' '''asMeters'''
::Returns the original length but enforces explicit printing in meters (i.e. prevents scaling prefix when printed).

*''aLength'' '''asMilliMeters''' / '''asMicroMeters''' / '''asNanoMeters''' / '''asCentiMeters'''
::Enforces explicit printing in millimeters ("mm"), micrometers ("µm"), nanometers ("nm") or centimeters ("cm").

*''aLength'' '''asKiloMeters'''
::Enforces explicit printing in kilometers ("km").

*''aLength'' '''asAngstrom'''
::Enforces explicit printing in angstrom ("Å").

*''aLength'' '''asInches''' / '''asFeet''' / '''asYards''' / '''asThous'''
::Enforces explicit printing in inches ("in"), feet ("ft"), yards ("yd") or thous ("thou").

*''aLength'' '''asFeetAndInches'''
::Enforces explicit printing in feet and inches (inches rounded to 1 fractional digit). <code>"1.80 meter asFeetAndInches"</code> will print itself as " 5′10.9″ "

*''aLength'' '''asFeetAndInchesRounded'''
::Enforces explicit printing in feet and rounded inches. <code>"1.80 meter asFeetAndInchesRounded"</code> will print itself as " 5′11″ "

*''aLength'' '''asAWGDiameter'''
::Enforces explicit printing in american wire gauge units ("AWG").

*''aLength'' '''asLandMiles'''
::Enforces explicit printing in land miles ("mi"). One land mile is 1.609344 km.

*''aLength'' '''asNauticalMiles'''
::Enforces explicit printing in nautical miles ("NM"). One nautical mile is 1.852 km.

*''aLength'' '''asLightYears'''
::Enforces explicit printing in lightyears ("ly"). A light year is 9460730472580.8 km.

*''aLength'' '''asLightSeconds'''
::Enforces explicit printing in lightseconds ("ls"). A light second is 299792.458 km.

*''aLength'' '''asAstronomicalUnits'''
::Enforces explicit printing in astronomicalUnits ("au"). An astronomical unit is 149597870.7 km.

*''aLength'' '''as:'''(Physic::PhysicalUnit unitNamed:'Mil')
::Enforces explicit printing in mil. A mil is 1/1000 of an inch. Usage of mils is not recommended, as it may be confused with millimeter. You can use the synonym "Thou" instead, which avoids this.

'''In a Formula''' ('...' asPhysicExpression value)
*<code>'100 m'</code>
::length in Meter. Also recognized: 'km', 'cm', 'mm', 'µm', 'nm', pm'

*<code>'100 mi'</code>
::length in Miles. Also recognized: 'in', 'ft', 'yd', 'mil', 'twip'

*<code>'10 Å'</code>
::length in Angstrom.

*<code>'1 au'</code>
::length in Astronomical Units. Also: 'ly', 'ls', 'pc'

=== Angle ===
Angles are measured in Radians, and the default printing is in "rad".
 The following operations return an instance of angle:

'''Instance Creation'''
*''aNumber'' '''radians'''
::Generates an angle of n radians.

*''aNumber'' '''degrees'''
::Generates an angle of n degrees (which prints itself as radians)

::Notice that Number can also compute the raw value (as scalar number) with "<code>degreesToRadians</code>" and "<code>radiansToDegrees</code>".

'''Unit Conversion'''
*''anAngle'' '''asDegrees'''
::Returns the same angle but enforces explicit printing in Degrees.

*''anAngle'' '''asRadians'''
::Returns the same angle but enforces explicit printing in Radians (i.e. to convert back from above degrees value).

*''anAngle'' '''asArcSec'''
::Returns the same angle but enforces explicit printing in arc seconds.

*''anAngle'' '''asArcMin'''
::Returns the same angle but enforces explicit printing in arc minutes.

*''anAngle'' '''asDegreeAndMinAndSec'''
::Returns the same angle but enforces explicit printing as d°m′s″ (e.g. "<code>90.1234 degrees asDegreeAndMinAndSec</code>" => 90°7′24″).

*''anAngle'' '''asGon'''
::Returns the same angle but enforces explicit printing in Gon (90 degrees = 100 gon).

'''Trigonometric'''
*''anAngle'' '''sin'''
::Angles understand the typical trigonometric messages '''sin''', '''cos''', '''tan''', '''cot''' (cotangent) and '''csc''' (cosecant).
::(Eg. you can write "<code>45 degrees sin</code>" to get 0.707106781186547)

=== Temperature ===
Temperature is measured in Kelvin, and the default printing is in "K".

'''Instance Creation'''
*''aNumber'' '''kelvin'''
::Generates an temperature-value of n Kelvin.

*''aNumber'' '''degreesCelcius'''
::Generates an temperature-value of n degrees Celsius.

*''aNumber'' '''degreesFahrenheit'''
::Generates an temperature-value of n degrees Fahrenheit.

*''aNumber'' '''rankine'''
::Generates an temperature-value of n degrees Rankine.

'''Unit Conversion'''
*''aTemperature'' '''asFahrenheit'''
::Returns the original temperature but enforces explicit printing in Fahrenheit.

*''aTemperature'' '''asCelsius'''
::Enforces explicit printing in degrees Celsius.

*''aTemperature'' '''asRankine'''
::Enforces explicit printing in Rankine.

*''aTemperature'' '''blackBodyWaveLength'''
::The wavelength corresponding to the temperature (returns a length).

'''In a Formula''' ('...' asPhysicExpression value)
*<code>900 K'</code>
::temperature in Kelvin.

*<code>900 °F'</code>
::temperature in Fahrenheit.

*<code>900 °C'</code>
::temperature in Celsius.

=== Frequency ===
Frequency is measured in Hertz, and the default printing is in "Hz", "kHz", "MHz" or whatever the print function chooses.

'''Instance Creation'''
*''aNumber'' '''hertz'''
::Generates a frequency-value of n hertz.

*''aNumber'' '''kiloHertz''' ''aNumber'' '''kilo''' '''hertz'''
::Generates a frequency-value of n kilohertz. Same as <CODE>n kilo hertz</CODE>.

*''aNumber'' '''megaHertz''' ''aNumber'' '''mega''' '''hertz'''
::Generates a frequency-value of n megahertz. Same as <CODE>n mega hertz</CODE>.

*''aNumber'' '''gigaHertz''' ''aNumber'' '''giga''' '''hertz'''
::Generates a frequency-value of n gigahertz. Same as <CODE>n giga hertz</CODE>.

*Physic::Frequency '''noteName:''' ''aString''
::Converts the name of a note (in international note notation) to a frequency. For example, <code>Physic::Frequency noteName: 'A4'</code> generates 440Hz. Valid note names are e.g. 'Bb4','C#5' or 'Db5'. I.e. the name within 'A' through 'G' followed by an optional 'b' (flat) or '#' sharp, followed by an optional octave number.

*Physic::Frequency '''midiNr:''' ''anInteger''
::Converts a Midi note number (0..127) to a frequency. For example, <code>Physic::Frequency midiNr: 69</code> generates 440Hz.

'''Unit Conversion'''
*''aFrequency'' '''asKiloHertz'''
::Returns the original frequency but enforces explicit printing in kilohertz ("kHz").

*''aFrequency'' '''asMegaHertz'''
::Enforces explicit printing in megahertz ("MHz").

*''aFrequency'' '''asGigaHertz'''
::Enforces explicit printing in gigahertz ("GHz").

'''Other'''
*''aFrequency'' '''noteName'''
::The name of the nearest note (equal tempered).

*''aFrequency'' '''midiNr'''
::The nearest Midi note number.

*''aFrequency'' '''addSemitones:''' ''nrOfSemitones''
::Returns the frequency ''nrOfSemitones'' higher (or lower, if negative).

*''aFrequency'' '''addOctaves:''' ''nrOfOctaves''
::Returns the frequency ''nrOfOctaves'' higher (or lower, if negative).

=== Energy ===
Energy is measured in Joule, and the default printing is in "J", "kJ" or whatever the print function chooses as reasonable scale.
 Many domains have their own preferred unit to use (atom physics use electron volts, energy industry uses wattHours and the oil industry uses btu).

'''Instance Creation'''
*''aNumber'' '''joule'''
::Generates an energy-value of n joule.

*''aNumber'' '''kiloJoule''' ''aNumber'' '''kilo''' '''joule'''
::Generates an energy-value of n kilojoule. Same as <CODE>n kilo joule</CODE>.

*''aNumber'' '''megaJoule''' ''aNumber'' '''mega''' '''joule'''
::Generates an energy-value of n megajoule. Same as <CODE>n mega joule</CODE>.

*''aNumber'' '''wattHours'''
::Generates an energy-value of n wattHours. Same as <CODE>n watt * 1 hours</CODE>.

*''aNumber'' '''kiloWattHours''' ''aNumber'' '''kilo''' '''wattHours'''
::Generates an energy-value of n kiloWattHours. Same as <CODE>n kilo wattHours</CODE> and also the same as <CODE>n kilo watt * 1 hours</CODE>.

*''aNumber'' '''megaWattHours''' ''aNumber'' '''mega''' '''wattHours'''
::Generates an energy-value of n megaWattHours. Same as <CODE>n mega wattHours</CODE> and also the same as <CODE>n mega watt * 1 hours</CODE>.

*''aNumber'' '''electronVolts'''
::Generates an energy-value of n electronVolts.

*''aNumber'' '''calories'''
::Generates an energy-value of n calories.

*''aNumber'' '''kiloCalories''' ''aNumber'' '''kilo''' '''calories'''
::Generates an energy-value of n kcal. Same as <CODE>n kilo calories</CODE>.

*''aNumber'' '''btu'''
::Generates an energy-value of n BTUs (British Thermal Units). 1 btu is 1055.06 J.

'''Unit Conversion'''
*''anEnergy'' '''asElectronVolts'''
::Present (i.e. prints) as electronVolts ("eV")

*''anEnergy'' '''asKiloWattHours'''
::Present as kiloWattHours ("kWh")

*''anEnergy'' '''asMegaWattHours'''
::Present as megaWattHours ("mWh")

*''anEnergy'' '''asGigaWattHours'''
::Present as gigaWattHours ("gWh")

*''anEnergy'' '''asCalories'''
::Present as calories ("cal")

*''anEnergy'' '''asKiloCalories'''
::Present as kilo calories ("kcal")

*''anEnergy'' '''asBTUs'''
::Present as BTUs (British Thermal Units)

*''anEnergy'' '''asTCEs'''
::Present as TCEs (Ton of Coal Equivalents)

'''In a Formula''' ('...' asPhysicExpression value)
*<code>'100 J'</code>
::power in joule. Also recognized: 'kJ', 'MJ', 'GJ', 'Nm', 'eV', 'keV', 'MeV', 'cal', 'kcal', 'btu', 'Wh', 'kWh', 'MWh', 'GWh', 'TWh'

=== Power ===
Power is a derived unit measured in Watt, and the default printing is in "W", "kW" or whatever the print function chooses as reasonable scale. Instances of "Power" are returned e.g. when multiplying an electric current by a voltage. Notice that there is a difference between VA and W in alternating current circuits. Here, Watt refers to the [https://en.wikipedia.org/wiki/AC_power#Active,_reactive,_apparent,_and_complex_power_in_sinusoidal_steady-state active power] or power in direct current circuits (or instantaneous power values) .

'''Instance Creation'''
*''aNumber'' '''watt'''
::Generates a power-value of n watt.

*''aNumber'' '''milliWatt'''
::Generates a power-value of n milliWatt. Same as "<CODE>n milli watt</CODE>".

*''aNumber'' '''kiloWatt'''
::Generates a power-value of n kiloWatt. Same as "<CODE>n kilo watt</CODE>".

*''aNumber'' '''megaWatt'''
::Generates a power-value of n megaWatt. Same as "<CODE>n mega watt</CODE>".

*''aNumber'' '''gigaWatt'''
::Generates a power-value of n gigaWatt. Same as "<CODE>n giga watt</CODE>".

*''aNumber'' '''teraWatt'''
::Generates a power-value of n teraWatt. Same as "<CODE>n tera watt</CODE>".

*''aNumber'' '''metric''' '''hp'''
::Generates a power-value of n metric horsePower (PS). Roughly 735.5 watt.

*''aNumber'' '''imperial''' '''hp'''
::Generates a power-value of n imperial horsePower (hp). Roughly 745.7 W watt.

'''Unit Conversion'''

*''aPower'' '''asMicroWatt'''
::Presents itself as µW

*''aPower'' '''asMilliWatt'''
::Presents itself as mW

*''aPower'' '''asKiloWatt'''
::Presents itself as kW

*''aPower'' '''asMegaWatt'''
::Presents itself as MW

*''aPower'' '''asGigaWatt'''
::Presents itself as GW

*''aPower'' '''asTeraWatt'''
::Presents itself as TW

*''aPower'' '''asDBm'''
::Presents itself as decibel based on milliwatt (1 mW is 0.0 dBm; 1 W is 30.0 dBm)

*''aPower'' '''asDBW'''
::Presents itself as decibel based on watt (1 W is 0.0 dBW; 1 kW is 30.0 dBW)

'''In a Formula''' ('...'asPhysicExpression value)
*<code>'100 W'</code>
::power in watt. Also recognized: 'mW', 'µW', 'kW', 'MW', 'GW', 'hp imp', 'p metric'

=== Force ===
Force is measured in Newton, and by default printed as such. Instances are created e.g. when multiplying a mass by an acceleration (in Smalltalk: "<code>1 kg * 10 meters / 1 seconds squared</code>").

'''Instance Creation'''
*''aNumber'' '''newton'''
::Generates a force-value of n newton.

*Physic::Force '''kilopond:''' ''kpNumber''
::Force from a given Kilopond amount. Notice that the Kilopond is no longer allowed (since 1978). So this should only be used when reading/converting old historic data.

*Physic::Force '''gramForce unitAmount:''' ''gfNumber''
::Returns a force value of ''gfNumber'' gramForce (gf). Notice that the "gramForce" message sent to the Force class returns the GramForce unit (not a value). Then, that unit gets the "unitAmount:" message, which returns a physical value (gf).

'''Unit Conversion'''

*''aForce'' '''asGramForce'''
::Presents itself as gf

*''aForce'' '''asTonForce'''
::Presents itself as tf (metric tons of force)

*''aForce'' '''asPoundsForce'''
::Presents itself as lbf

*''aForce'' '''asKiloNewton'''
::Presents itself as kN

*''aForce'' '''asMilliNewton'''
::Presents itself as mN

*''aForce'' '''asNewton'''
::Presents itself as N (i.e. without scale prefix)

=== Area ===
Area is a derived unit based on length in meters and measured in square meter. The default printing is in "m²". Instances of "Area" are created e.g. when multiplying two length values or when dividing a volume by a length.

'''Instance Creation'''
*''aNumber'' '''squareMeter'''
::Generates an area-value of n square meters (m²).

*''aNumber'' '''squareMilliMeter'''
::Generates an area-value of n square millimeters.

*''aNumber'' '''squareKiloMeter'''
::Generates an area-value of n square kilometers (1000*1000 m²).

*''aNumber'' '''hectare'''
::Generates an area-value of n hectares. Same as <CODE>n hecto are</CODE> or 10000 m².

*''aNumber'' '''are'''
::Generates an area-value of n ares. 1 are being 100 m².

*''aNumber'' '''squareMiles'''
::Generates an area-value of n square miles. 1 sq mi being 2589988.110336 m².

*''aNumber'' '''squareFeet'''
::Generates an area-value of n square feet. 1 sq ft being 0.0929 m².

*''aNumber'' '''acres'''
::Generates an area-value of n acres. 1 acre being 4046.856 m².

'''Conversion'''

*''anArea'' '''asAre'''
::Presents itself as are (1 are = 100 m²)

*''anArea'' '''asAWG'''
::Presents itself as american gauge units (wire thickness)

*''anArea'' '''asHectare'''
::Presents itself as hectare ("ha")

*''anArea'' '''asSquareKiloMeters'''
::Presents itself as square kilometer ("km²")

*''anArea'' '''asSquareMeters'''
::Presents itself as square meter ("m²") without scale prefix

*''anArea'' '''asSquareFeet'''
::Presents itself as square feet ("sq ft")

*''anArea'' '''asAcres'''
::Presents itself as acres ("ac")

*''anArea'' '''asSquareMiles'''
::Presents itself as square miles ("sq mi") (based on a land mile being 1609.344 m)

=== Volume ===
Volume is a derived unit based on length in meters and measured in cubic meter. The default printing is in "m³", although the print function may choose to print in liters "l", or milli liters "ml" etc. Instances of "Volume" are created e.g. when multiplying an area by a length or when cubing a length.

'''Instance Creation'''
*''aNumber'' '''cubicMeter''' ''aNumber'' '''cubic''' '''meter'''
::Generates an volume-value of n cubic meters (1000 l). The alternative "1 cubic meter" uses the "cubic" prefix.

*''aNumber'' '''liter'''
::Generates an volume-value of n liters.

*''aNumber'' '''milliLiter'''
::Generates a volume-value of n milliliters. Same as "<CODE>n milli liter</CODE>".

*''aNumber'' '''hectoLiter'''
::Generates a volume-value of n hectoliters. Same as "<CODE>n hecto liter</CODE>".

*''aNumber'' '''barrel''' ''aNumber'' '''american''' '''barrel'''
::Generates a volume of n barrels (oil volume measurement). 1 (oil) barrel is 158.987 liters. This is an US oil barrel (aka "blue barrel"), which is different from an imperial barrel and also different from beer/wine barrels.

*''aNumber'' '''flozIMP''' ''aNumber'' '''flozGB''' ''aNumber'' '''british''' '''floz''' ''aNumber'' '''imperial''' '''floz'''
::Generates a volume of n imperial fluid ounces (0.02841 liter or 28.4130625 ml).

*''number'' '''flozUS''' ''number'' '''american''' '''floz'''
::Generates a volume of n US fluid ounces (0.02957 liter or 29.5735295625 ml).

*''aNumber'' '''pintIMP''' ''aNumber'' '''pintGB''' ''aNumber'' '''british''' '''pint''' ''aNumber'' '''imperial''' '''pint'''
::Generates a volume of n imperial pints (568.26125 ml).

*''aNumber'' '''pintUS''' ''aNumber'' '''american''' '''pint'''
::Generates a volume of n US pints (473.176473 ml). It seems that british drinkers get more for the pint ;-)

*''aNumber'' '''quartIMP''' ''aNumber'' '''quartGB''' ''aNumber'' '''british''' '''quart''' ''aNumber'' '''imperial''' '''quart'''
::Generates a volume of n imperial quarts (1.1365 liter).

*''aNumber'' '''quartUS''' ''aNumber'' '''american''' '''quart'''
::Generates a volume of n US quarts (946.353 ml).

*''aNumber'' '''gallonsIMP''' ''aNumber'' '''gallonsGB''' ''aNumber'' '''british''' '''gallons''' ''aNumber'' '''imperial''' '''gallons'''
::Generates a volume of n imperial gallons (4.5461 liter).

*''aNumber'' '''gallonsUS''' ''aNumber'' '''american''' '''gallons'''
::Generates a volume of n US gallons (3.7854 liter).

'''Converting'''

*''aVolume'' '''asCubicMeters'''
::Presents itself as cubic meters ("mˆ3") (not as "ml" or "l")

*''aVolume'' '''asLiters'''
::Presents itself as liters ("l"). (not as "ml" or "mˆ3")

*''aVolume'' '''asHectoLiters'''
::Presents itself as hectoliters ("hl") (not as "ml", "l" or "mˆ3")

*''aVolume'' '''asMilliLiters'''
::Presents itself as milliliters ("ml") (not as "l" or "mˆ3")

*''aVolume'' '''asCentiLiters'''
::Presents itself as centiliters ("cl") (not as "l" or "mˆ3")

*''aVolume'' '''asDeciLiters'''
::Presents itself as deciliters ("dl") (not as "l" or "mˆ3")

*''aVolume'' '''asCubicInches'''
::Presents itself as cubic inches ("cuin")

*''aVolume'' '''asFlozGB'''
::Presents itself as imperial fluid ounces ("imp fl oz")

*''aVolume'' '''asFlozUS'''
::Presents itself as US fluid ounces ("us fl oz")

*''aVolume'' '''asGallonsGB'''
::Presents itself as imperial gallons ("imp ga")

*''aVolume'' '''asGallonsUS'''
::Presents itself as US gallons ("us ga")

'''Print Setup'''

*Physic::Volume '''literAbbrev:''' 'L'
::configure to print "L" (upper case) instead of "l" (lower case letter "L"). (NIST recommendation in US, to avoid confusion with the digit '1'). Other useful arguments are 'ℓ'or 'ltr'.

'''In a Formula''' ('...'asPhysicExpression value)
*<code>'100 L'</code>
::volume in Liter. Also recognized: 'dL', 'cL', 'ml', 'µL', 'hL'

*<code>'100 gal'</code>
::volume in US gallons. Also recognized: 'bbl','floz', with optional modifier: american ('gal us') and imperial ('gal imp').

=== Velocity (Speed) ===
Velocity is a derived unit based on length in meters and measured in meters per second. The default printing is in "m/s". Instances of "Velocity" are created e.g. when dividing a length by a time duration.

'''Instance Creation'''
*''aNumber'' '''meterPerSecond'''
::Generates a velocity of n meters per second.

*''aNumber'' '''kiloMeterPerHour'''
::Generates a velocity of n km per hour.

*''aNumber'' '''milesPerHour'''
::Generates a velocity of n mph.

*''aNumber'' '''knots'''
::Generates a velocity of n nautical miles per hour.

*Physic::NatureConstants '''lightspeed'''
::Speed of light in vacuum

*Physic::NatureConstants '''soundspeed'''
::Speed of sound (in dry air at 20°C)

'''Conversion'''

*''aVelocity'' '''asKiloMetersPerHour'''
::Presents itself as km/h

*''aVelocity'' '''asMilesPerHour'''
::Presents itself as mph

*''aVelocity'' '''asKnots'''
::Presents itself as nautical knots (kn). 1 knot being 0.514 m/s or 1.852 km/h ("1.0 knots asKiloMetersPerHour").

'''In a Formula''' ('...'asPhysicExpression value)
*<code>'100 m/s'</code>
::speed in Meter per second. Also recognized: 'km/h', 'cm/s', 'mph', 'mi/h'

*<code>'100 kn'</code>
::speed in Knots.

=== Acceleration ===

Velocity is a derived unit based on length in meters and measured in meters per second per second. The default printing is in "m/s²". Instances of "Acceleration" are created e.g. when dividing a velocity by a time duration.

'''Instance Creation'''
*''aNumber'' '''metersPerSecondPerSecond'''
::Generates an acceleration of n m/s².

*Physic::NatureConstants '''earthGravity'''
::Returns 9.80665 m/s²

*Physic::NatureConstants['planets']['earth']['gravity'|
::also returns 9.80665 m/s²

'''Conversion'''
*''anAcceleration'' '''asGForce'''
::Presents itself as "g" (multiples of 9.81m/s²).

'''Queries'''
*''anAcceleration'' '''distanceAfter:''' ''aTimeDuration''
::Computes the distance travelled when a constant acceleration is applied for some time.

*''anAcceleration'' '''speedAfter:''' ''aTimeDuration''
::Computes the speed when a constant acceleration is applied for some time.

=== Pressure ===
Pressure is a derived unit measured in Pascal. The default printing is in "Pa". Instances of "Pressure" are created e.g. when dividing a force by an area.

'''Instance Creation'''
*''aNumber'' '''pascal'''
::Generates a pressure value of n pascal.

*''aNumber'' '''hectoPascal'''
::Generates a pressure value of n hectoPascal. Same as "<CODE>n hecto pascal</CODE>".

'''Conversion'''

*''aPressure'' '''asAtm'''
::Presents itself as atm (atmospheres)

*''aPressure'' '''asBar'''
::Presents itself as bar

*''aPressure'' '''asHectoPascal'''
::Presents itself as hPa

*''aPressure'' '''asPascal'''
::Presents itself as Pa

*''aPressure'' '''asPSI'''
::Presents itself as psi (pounds per square inch)

*''aPressure'' '''asTorr'''
::Presents itself as torr

*''aPressure'' '''asMmHg'''
::Presents itself as mmHg (millimeter of mercury). Same magnitude as torr, but this is typically used in medical domains.

'''In a Formula''' ('...'asPhysicExpression value)
*<code>'100 Pa'</code>
::pressure in pascal. Also recognized: 'hPa', 'kPa', 'MPa', 'GPa', 'mPa', 'bar', 'atm', 'psi', 'mmH2O', 'mmHg', 'torr'

=== Voltage ===
Voltage is a derived unit measured in Volt. The default printing is in "V", "mV", "kV" as appropriate.

'''Instance Creation'''
*''aNumber'' '''volts'''
::Generates an electrical voltage of n volts.

*''aNumber'' '''milliVolt''' ''aNumber'' '''milli''' '''volt'''
::Generates a voltage of n millivolt.

*''aNumber'' '''microVolt''' ''aNumber'' '''micro''' '''volt'''
::Generates a voltage of n microvolt.

*''aNumber'' '''kiloVolt''' ''aNumber'' '''kilo''' '''volt'''
::Generates a voltage of n kilovolt.

'''Conversion'''
*''aVoltage'' '''asDBV'''
::Presents itself as as DBV (decibel voltage Lv)

*''aVoltage'' '''asDBu'''
::Presents itself as as DBu (decibel voltage Lu)

*''aVoltage'' '''asKiloVolts'''
::Presents itself as kV

*''aVoltage'' '''asMilliVolts'''
::Presents itself as mV

*''aVoltage'' '''asMicroVolts'''
::Presents itself as µV

*''aVoltage'' '''asNanoVolts'''
::Presents itself as nV

*''aVoltage'' '''asVolts'''
::Presents itself as V (without scale prefix)

=== Electric Current ===
A derived unit measured in Ampere. The default printing is in "A", "mA", "kA" as appropriate. Instances of "Current" are created e.g. when dividing an electric charge by a time duration.

'''Instance Creation'''
*''aNumber'' '''ampere'''
::Generates an electric current of n ampere.

*''aNumber'' '''milliAmpere''' ''aNumber'' '''milli''' '''ampere'''
::Generates an electric current of n milliampere.

*''aNumber'' '''microAmpere''' ''aNumber'' '''micro''' '''ampere'''
::Generates an electric current of n microampere.

'''Conversion'''
*''aCurrent'' '''asKiloAmperes'''
::Presents itself as "kA"

*''aCurrent'' '''asMilliAmperes'''
::Presents itself as "mA"

*''aCurrent'' '''asMicroAmperes'''
::Presents itself as "uA"

*''aCurrent'' '''asNanoAmperes'''
::Presents itself as "nA"

*''aCurrent'' '''asPicoAmperes'''
::Presents itself as "pA"

*''aCurrent'' '''asAmperes'''
::Presents itself as "A"

=== Electric Resistance ===
A derived unit measured in Ohm. The default printing is in "Ω", "kΩ", "MΩ" as appropriate.

'''Instance Creation'''
*''aNumber'' '''ohm'''
::Generates an electric resistance of n ohm.

*''aNumber'' '''kiloOhm''' (or '''kilohm''')
::Generates an electric resistance of n kilo Ohm.

*''aNumber'' '''megaOhm'''
::Generates an electric resistance of n megaOhm.

*''Physic::ElectricResistance'' '''colorCode: '''#(name1 name2 name3 [name4])
::Generates an electric resistance given a resistor's color code. The argument must be a 3 or 4 element collection (array), and the name_i elements must be color name symbols, i.e. one of {black, brown, red, orange, yellow, green, blue, violet, grey, white). For example, "Physic::ElectricResistance' colorCode:#(yellow violet red)" returns 4700 Ω.

'''Conversion'''
*''aResistance'' '''asKiloOhms''' (or '''asKilohms''')
::prints as "kΩ".

*''aResistance'' '''asMegaOhms'''
::prints as "MΩ".

*''aResistance'' '''asOhms'''
::prints as "Ω".

*''aResistance'' '''asMilliOhms'''
::prints as "mΩ".

'''Additional Arithmetic Operations'''
* ''aResistance1'' '''|''' ''aResistance2''
::Computes the resistance of resistors in parallel (as opposed to "'''+'''" which adds the values and thus computes resistors in series)

=== Electric Capacitance ===
A derived unit measured in Farad. The default printing is in "F", "uF", "nF", "pF" as appropriate.

'''Instance Creation'''
*''aNumber'' '''farad'''
::Generates an electric capacitance of n farad.

*''aNumber'' '''microFarad'''
::Generates an electric capacitance of n microfarad.

*''aNumber'' '''nanoFarad'''
::Generates an electric capacitance of n nanofarad.

*''aNumber'' '''picoFarad'''
::Generates an electric capacitance of n picofarad.

'''Conversion'''

*''aCapacitance'' '''asMicroFarads'''
::Presents itself as "uF"

*''aCapacitance'' '''asNanoFarads'''
::Presents itself as "nF"

*''aCapacitance'' '''asPicoFarads'''
::Presents itself as "pF"

*''aCapacitance'' '''asFarads'''
::Presents itself as "F"

'''Additional Arithmetic Operations'''
* ''aCapacitance1'' '''|''' ''aCapacitance2''
::Computes the capacitance of caps in parallel (same as "'''+'''" here)

=== Electric Charge ===
A unit measured in Coulomb. The default printing is in "C". Instances of "Charge" are created e.g. when multiplying an electric current by a time duration.

'''Instance Creation'''
*''aNumber'' '''coulomb'''
::Generates an electric charge of n coulomb.

'''Conversion'''
*''aCharge'' '''asAmpereSeconds'''
::Presents itself as "As" (which is also a coulomb, but "As" might be preferred in some domains)

*''aCharge'' '''asAmpereHours'''
::Presents itself as "Ah"

*''aCharge'' '''asElementaryCharges'''
::Presents itself as "q". 1 coulomb corresponds to 6.241e+18 elementary charges

*''aCharge'' '''asNumberOfElectrons'''
::Returns the above as a scalar number

=== Inductance ===
A unit measured in Henry (H).

'''Instance Creation'''
*''aNumber'' '''henry'''
::Generates an inductance of n henry.

'''Conversion'''
*''anInductance'' '''asMilliUnitValue'''
::Presents itself as "mH"
*''anInductance'' '''asMicroUnitValue'''
::Presents itself as "µH"

'''Additional Arithmetic Operations'''
* ''anInductance1'' '''|''' ''anInductance2''
::Computes the inductance of coils in parallel (as opposed to "'''+'''" which adds the values and thus computes coils in series)

=== LuminousIntensity ===
A unit measured in Candela (cd).

'''Instance Creation'''
*''aNumber'' '''candela'''
::Generates a luminousIntensity of n candela.

=== Luminance ===
A unit measured in Lux (lx). Results from dividing a luminous intensity by an area.

'''Instance Creation'''
*''aNumber'' '''lux'''
::Generates a luminance of n lux.

=== MagneticFlux ===
A unit measured in Weber (Wb). Results from multiplying a voltage by a time.

=== MagneticFluxDensity ===
A unit measured in Tesla (T). Results from dividing a magnetic flux by an area.

=== CurrentDensity ===
A unit measured in A/m². Results from dividing an electric current by an area.

=== Viscosity ===
DynamicViscosity unit measured in Poise (P) and KinematicViscosity measured in Stokes (St).

=== Electric Conductance ===
A unit measured in Siemens (S) which is s³·m⁻²·kg⁻¹·A² (dimension T³·L⁻²·M⁻¹·I²). This is the reciprocal of the electric resistance.

=== Mass Density ===
A unit measured in kg/m³ (dimension L⁻³·M). Instances are created e.g. when dividing a mass by a volume.

'''Conversion'''
*''aMassDensity'' '''asGramPerCubicCentimeter'''
::Presents itself as g/cm³. For example:
::: massSun := Physic::NatureConstants['sun']['mass'].
::: volumeSun := Physic::NatureConstants['sun']['Volume'].
::: (massSun / volumeSun) asGramPerCubicCentimeter
:::: => 1.41028368794326 g/cm³

== English Engineering and Imperial Units (EEU) ==

See [https://en.wikipedia.org/wiki/English_Engineering_Units English Engineering Units] and [https://en.wikipedia.org/wiki/Imperial_and_US_customary_measurement_systems Imperial and US customary measurement systems].

=== EEU/Imperial Length ===

'''Unit Access'''
* PhysicalUnit::Length '''inches'''
::Returns a unit which represents its values as "in"

* PhysicalUnit::Length '''feet'''
::Returns a unit which represents its values as "ft"

* PhysicalUnit::Length '''yards'''
::Returns a unit which represents its values as "yd"

* PhysicalUnit::Length '''thous'''
::Returns a unit which represents its values as "thous"

* PhysicalUnit::Length '''landMiles'''
::Returns a unit which represents its values as "mi"

* PhysicalUnit::Length '''nauticalMiles'''
::Returns a unit which represents its values as "nmi"

'''Instance Creation'''
* (PhysicalUnit::Length '''feet''') unitAmount: '''n'''
::Generates a length of n feet.

* ''someUnit'' unitAmount: '''n'''
::Once you have any units at hand, you'll get a physical value with <aUnit> unitAmount: <n>

'''Number Protocol'''
* ''aNumber'' '''feet''' (prints itself with SI unit 'm')
* ''aNumber'' '''feet''' '''asFeet''' (prints itself with unit 'ft')
* ''aNumber'' '''inches''' (prints itself with SI unit 'm')
* ''aNumber'' '''inches''' '''asInches''' (prints itself with unit 'in')
* ''aNumber'' '''yards'''
* ''aNumber'' '''yards''' '''asYards''' (prints itself with unit 'yd')
* ''aNumber'' '''landMiles'''
* ''aNumber'' '''landMiles''' '''asLandMiles''' (prints itself with unit 'mi')
* ''aNumber'' '''nauticalMiles'''
* ''aNumber'' '''nauticalMiles''' '''asNauticalMiles''' (prints itself with unit 'nmi')

=== EEU/Imperial Area ===

'''Unit Access'''
* PhysicalUnit::Area '''squareInches'''
::Returns a unit which represents its values as "sq in"

* PhysicalUnit::Area '''squareFeet'''
::Returns a unit which represents its values as "sq ft"

* PhysicalUnit::Area '''squareMiles'''
::Returns a unit which represents its values as "sq mi"

* PhysicalUnit::Area '''acres'''
::Returns a unit which represents its values as "acre"

'''Number Protocol'''
* ''aNumber'' '''square inches''' (prints itself with SI unit 'm²')
* ''aNumber'' '''square inches''' '''asSquareInches''' (prints itself with unit 'sq in')
* ''aNumber'' '''square feet''' (prints itself with SI unit 'm²')
* ''aNumber'' '''square feet''' '''asSquareFeet''' (prints itself with unit 'sq ft')
* ''aNumber'' '''square miles''' (prints itself with SI unit 'm²')
* ''aNumber'' '''square miles''' '''asSquareFeet''' (prints itself with unit 'sq mi')
* ''aNumber'' '''acres''' (prints itself with SI unit 'm²')
* ''aNumber'' '''acres''' '''asAcres''' (prints itself with unit 'acre')

=== EEU/Imperial Volume ===

'''Unit Access'''
* PhysicalUnit::Volume '''cubicInches'''
::Returns a unit which represents its values as "cu in"

* PhysicalUnit::Volume '''cubicFeet'''
::Returns a unit which represents its values as "cu ft"

* PhysicalUnit::Volume '''cubicYards'''
::Returns a unit which represents its values as "cu yd"

* PhysicalUnit::Volume '''squareMiles'''
::Returns a unit which represents its values as "sq mi"

* PhysicalUnit::Volume '''gallonsIMP'''
::Returns a unit which represents its values as imperial gallons "imp gal"

* PhysicalUnit::Volume '''gallonsUS'''
::Returns a unit which represents its values as US gallons "US gal"

* PhysicalUnit::Volume '''pintsIMP'''
::Returns a unit which represents its values as imperial pints "imp pt"

* PhysicalUnit::Volume '''pintsUS'''
::Returns a unit which represents its values as US pints "US pt"

* PhysicalUnit::Volume '''barrelsIMP'''
::Returns a unit which represents its values as imperial barrels "bbl. imp"

* PhysicalUnit::Volume '''barrelsUS'''
::Returns a unit which represents its values as US pints "bbl."

'''Number Protocol'''
* ''aNumber'' '''cubic inches''' (prints itself with SI unit 'm³')
* ''aNumber'' '''cubic inches''' '''asCubicInches''' (prints itself with unit 'cu in')
* ''aNumber'' '''cubic feet''' (prints itself with SI unit 'm³')
* ''aNumber'' '''cubic feet''' '''asCubicFeet''' (prints itself with unit 'cu ft')
* ''aNumber'' '''cubic yards''' (prints itself with SI unit 'm³')
* ''aNumber'' '''cubic yards''' '''asCubicFeet''' (prints itself with unit 'cu yd')
* ''aNumber'' '''imperial pints''' (prints itself with SI unit 'm³')
* ''aNumber'' '''imperial pints''' '''asPintsIMP''' (prints itself with unit 'imp pt')
* ''aNumber'' '''american pints''' (prints itself with SI unit 'm³')
* ''aNumber'' '''american pints''' '''asPintsUS''' (prints itself with unit 'US pt')
* ''aNumber'' '''imperial gallons''' (prints itself with SI unit 'm³')
* ''aNumber'' '''imperial gallons''' '''asGallonsIMP''' (prints itself with unit 'imp gal')
* ''aNumber'' '''american gallons''' (prints itself with SI unit 'm³')
* ''aNumber'' '''american gallons''' '''asGallonsUS''' (prints itself with unit 'US gal')
* ''aNumber'' '''imperial barrels''' (prints itself with SI unit 'm³')
* ''aNumber'' '''imperial barrels''' '''asBarrelsIMP''' (prints itself with unit 'bbl. imp')
* ''aNumber'' '''american barrels''' (prints itself with SI unit 'm³')
* ''aNumber'' '''american barrels''' '''asBarrelsUS''' (prints itself with unit 'bbl.')

=== EEU/Imperial Mass ===

'''Unit Access'''
* PhysicalUnit::Mass '''poundMass'''
::Returns a unit which represents its values as "lb"

* PhysicalUnit::Mass '''ounces'''
::Returns a unit which represents its values as "oz"

* PhysicalUnit::Mass '''troyOunces'''
::Returns a unit which represents its values as "oz t"

'''Number Protocol'''
* ''aNumber'' '''pounds''' (prints itself with SI unit 'kg')
* ''aNumber'' '''pounds''' '''asPounds''' (prints itself with unit 'lb')
* ''aNumber'' '''troyOunces''' (prints itself with unit 'kg')
* ''aNumber'' '''troyOunces''' '''asTroyOunces''' (prints itself with unit 'oz t')

=== EEU/Imperial Force ===

'''Unit Access'''
* PhysicalUnit::Mass '''poundForce'''
::Returns a unit which represents its values as "lbf"

* PhysicalUnit::Mass '''poundal'''
::Returns a unit which represents its values as "pdl"

=== EEU/Imperial Power ===

'''Unit Access'''
* PhysicalUnit::Mass '''poundForce'''
::Returns a unit which represents its values as "lbf"

* PhysicalUnit::Mass '''poundal'''
::Returns a unit which represents its values as "pdl"

=== EEU/Imperial Energy ===

'''Unit Access'''
* PhysicalUnit::Mass '''btu'''
::Returns a unit which represents its values as "btu"

=== EEU/Imperial Temperature ===

'''Unit Access'''
* PhysicalUnit::Temperature '''fahrenheit'''
::Returns a unit which represents its values as "°F"

* PhysicalUnit::Temperature '''rankine'''
::Returns a unit which represents its values as "°R"

== Defining Additional Unit Converters ==

You can define additional unit converters as ''ConvertedUnit'' as follows:
myUnit := Physic::ConvertedUnit
name:unitName
baseUnit:baseUnit
unitString:unitString
unitValueBlock:unitValueBlock
baseUnitValueBlock:baseUnitValueBlock

Where
* ''baseUnit'' is the underlying base (SI) unit,
* ''unitString'' is the string used when printing,
* ''unitValueBlock'' is a Smalltalk block to compute the unit value from a base unit value and
* ''baseUnitValueBlock'' is a Smalltalk block to compute the base unit value from the unit value.

==== Example: Cubic Inch Unit ====
For example, to get volumes printed as cubic inches, you could define 1):
cI := Physic::ConvertedUnit
name:'CubicInches'
baseUnit:(Physic::Volume)
unitString:'in³'
unitValueBlock:[:cubicMeters |
cubicMeters * 61023.7440947323
]
baseUnitValueBlock:[:cubicInches|
cubicInches / 61023.7440947323
]

i.e. to convert from SI base-units, which are cubic meters, into the converted cubic inches, we have to multiply by 61023.7440947323. And vice versa, we have to divide. 61023.7440947323 is the number of cubic inches per cubic meter.

Then create a new physical value for your volume with:
cI unitAmount:volumeInCubicMeters

==== Example: Gummy Bear Unit ====
Or, to present a mass in units of gummy-bears, assuming one bear weighs 1.1g 2):,
bearUnit :=
Physic::ConvertedUnit
name:'Haribo'
baseUnit:(Physic::Mass)
unitString:'bears'
unitValueBlock:[:kiloGram| kiloGram * 1000 / 1.1]
baseUnitValueBlock:[:bears| bears * 1.1 / 1000]

and then take a 150g bag of bears and ask it to print itself on an output stream:
bagOfBears := bearUnit baseUnitAmount:0.150. "/ 0.15 for 150g, because the base unit is kiloGram
bagOfBears printOn:Transcript
gives:
=> "136.363636363636 bears"

Notice, that bearUnit ("Haribo") is still a unit of mass;
we can add another kilogram to those bears:
bagOfBears + 1 kilo gram
and get more bears:
=> 1045.45454545455 bears

You can also convert any mass into gummy-bears:
(1 kiloGram as:bearUnit) floor
gives:
=> 909.0 bears

Notes:
 1) this is only an example; you actually don't need that, as volumes already support conversion to cubicInches (see asCubicInches below)
 2) the author does not know what the actual mass of a gummy bear is ;-)

== Instance Creation via Number Operators ==
The Number class hierarchy provides a number of instance creation messages for unit values. As described above, a frequency value can be created by sending a "hertz" message to any number:
440 hertz

The following lists a subset of messages which are provided in Number (for some, both abbreviations and british/US spelling versions are provided):
* Area
: acre, acres, are, hectare, squareMeter, squareCentiMeter, squareFeet, squareInches, squareKiloMeter, squareMiles, squareMilliMeter, squareYard.
: You can also use the "square" prefix with meter, feet, inches, yards, etc. As in "<CODE>10 square feet</CODE>".
* Energy
: btu, calories, electronVolts, wattHours,
* Frequency
: hertz, kiloHertz, megaHertz, gigaHertz, Hz, kHz, MHz, GHz
* Length
: angstrom, astronomicalUnits, centiMeter, chineseFeet, chineseMiles, feet, meter, yards, lightYears, miles, seaMiles, kiloMeter, milliMeter, ...
* Mass
: atomicMassUnits, gram, kiloGram, kg, microGram, troyPounds, troyOunces, ...
: You can use the "american"/"british"/"imperial"/"troy" prefixes on "ounces". As in "<CODE>2 troy ounces</CODE>".
* Pressure
: hectoPascal, torr, ...
* Temperature
: degreesCelsius, degreesFahrenheit, kelvin, ...
* Velocity
: centiMetersPerSecond
* Volume
: gallonsGB, gallonsUS, liter, litre, hectoLiter, hectoLitre, barrel, cubicInches, cubicMeter, cubicCentiMeter, cubicMilliMeter, cubicFeet, cubicKiloMeter, flozGB, flozUS, fluidOuncesGB, fluidOuncesUS, ...
: You can also use the "cubic" prefix with meter, feet, inches, etc. Eg. "<CODE>10 cubic feet</CODE>".
: And you can use the "american"/"british"/"imperial" prefixes on "gallons", "pints", "quarts". Eg. "<CODE>1 british pint</CODE>".
* Data
: bits, bytes, kiloByte, megaByte, gigaByte, kibiByte, mebiByte, gibiByte, ...
* Electricity
: volt, ampere, ohm, coulomb, farad, ampereHours, watt, voltAmpere, henry, ...
* Other
: candela, becquerel, tesla, ...

For a full list, open a SystemBrowser, navigate to the ArithmeticValue class and select the "physics-unit converting" category.

All of those can be used with the kilo, mega, giga etc. prefixes.

== Arithmetic ==

Arithmetic on physical values will generate an appropriate physical value with its own unit.
E.g., when multiplying a velocity by a time, you will get a distance, or when dividing a distance by a time, you will get a velocity.

The following lists some of the possible results.
Be aware that the units are ignorant of any relativistic effects. They compute their values according to classical Newtonian mechanics.

=== Velocity Arithmetic ===

distance = velocity * time

3 meterPerSecond => 3 m/s 
1 meterPerSecond * 10 seconds => 10 m 
10 kiloMetersPerHour * 30 minutes => 5000 m
30 meter / 2 seconds => 15 m/s
10 meter / 1 seconds * 20 seconds => 20 m

=== Acceleration Arithmetic ===

speed = acceleration * time

1 meterPerSecondPerSecond * 10 seconds => 10 m/s 
(1 meterPerSecondPerSecond distanceAfter:1 hours) => 6480.0 km
1 meterPerSecond / 10 seconds => 0.1 m/s²
10 meter / 2 seconds / 5 seconds => 1 m/s²
(9.81 meter / 1 seconds squared) * 1 hours => 70632 m/s

=== Mass Arithmetic ===

force = mass * acceleration

1 kiloGram * 1 meterPerSecondPerSecond => 1 N
1 kilo gram * 1 meter / 1 seconds / 1 seconds => 1 N
1 kilo gram * 100 centi meter / 1 seconds squared => 1 N
1 newton / 2 kiloGram => (1/2) m/s²

=== Electric Arithmetic ===
current = voltage / resistance
 charge = voltage * capacitance
 charge = current * time

10 volt / 220 ohm => 45.45 mA
150 ohm * 20 milliAmpere => 3 V 
0.5 ampere * 0.5 seconds => 0.25 C
100.0 micro farad * 100 volt => 0.01 C
10.0 micro farad * 100 ohm => 1.0 ms (the RC time constant)
100 pico farad * 5 volt / 10 milli ampere => 50ns

=== Energy & Power Arithmetic ===

10 ampere * 220 volt => 2200 W 
10 ampere * 220 volt * 10 hours => 79.2 MJ 
10 kiloWatt * 10 hours => 360.0 MJ 
(10 kiloWatt * 10 hours ) asKiloWattHours => 100 kWh

=== Math Functions and Trigonometric ===
Angles respond to trigonometric operations:
45 degrees sin => 0.707106781186547 
Float pi radian cos => -1.0

If useful, square and cubic root can be computed:
25 squareFeet sqrt => 1.524 m
25 squareFeet sqrt asFeet => 5.0 ft
5 feet * 5 feet. => 2.322576 m²
10 liter cbrt => 0.2154 m

=== Comparing ===
If the unit's amount is a float, the usual float comparison problems arise (see chapter on [[Numeric_Limits/en#Inexact_Float_and_Double_Numbers|comparing float numbers]]).
 You should not compare physical values for equal values; instead give an accepted error range. Either as fraction (e.g. percentage) or in the number accepted eps steps:

25.0 squareFeet sqrt = 5 feet => false
25.0 squareFeet sqrt isAlmostEqualTo: 5 feet withError:0.00001 => true
25.0 squareFeet sqrt isAlmostEqualTo: 5 feet nEpsilon:2. => true

=== Rounding & Truncating ===
Rounding and truncation operations are provided which generate a unit with the amount processed like the corresponding number operations:

1.0 meter floor => 1 m 
1.1 meter floor => 1 m 
1.7 meter floor => 1 m 

1.0 meter ceiling => 1 m 
1.1 meter ceiling => 2 m 
1.7 meter ceiling => 2 m 

1.0 meter rounded => 1 m 
1.1 meter rounded => 1 m 
1.7 meter rounded => 2 m 

1.15 meter roundTo:0.1 => 1.1 m 
1.15 meter roundTo:0.2 => 1.2 m
1.15 meter roundTo:0.5 => 1 m
1.04 meter roundTo:0.2 => 1 m 
1.1 meter roundTo:0.2 => 1.2 m

2 meter negated => -2 meter

(4/3) meter roundedToScale:0 => 1 m
(4/3) meter roundedToScale:1 => 1.3 m
(4/3) meter roundedToScale:2 => 1.33 m
(4/3) meter roundedToScale:3 => 1.333 m

(5/3) meter roundedToScale => 1.67 m 
(5/3) meter roundedToScale:0 => 2 m 
(5/3) meter roundedToScale:1 => 1.7 m 
(5/3) meter roundedToScale:2 => 1.67 m 
(5/3) meter roundedToScale:3 => 1.667 m

Be careful with roundedToScale: it will round the unit (which in the above case is meter).
If the value is small (i.e. in the cm range), rounding to scale 2 will round to 1/100 meter,
which might later print strange unexpected values.
Thus it is best to convert the result into a desired range (i.e. asCentiMeters) and round this:
eg:
15.012 centiMeter => 0.15012 m
15.0120 centiMeter roundedToScale:2 => 0.15 m
15.0120 centiMeter asCentiMeters roundedToScale:2 => 15.01 cm

== Formula Evaluation ==

Formulae can be parsed and further processed by use of the Physic::Parser class.

* <CODE>Physic::Parser</CODE> '''parse:''' ''aString'' generates a parse tree for further processing

* ''aString'' '''asPhysicExpression''' same

* <CODE>Physic::Parser</CODE> '''evaluate:''' ''aString'' parses and evaluates

Generated parse trees can be further processed with:

* ''aParseTree'' '''value''' evaluates the tree; variables are resolved to be units or nature constants

* ''aParseTree'' '''valueIn:''' ''aDictionary'' evaluates the tree providing variable values

* ''aParseTree'' '''valueWith:''' ''anAssociation'' evaluates the tree providing a single variable value in the form "( 'name' -> value )" (i.e. a Smalltalk Association instance).

* ''aParseTree'' '''valueWith:''' ''assoc1'' [ '''with:''' ''assoc2'' ...] ditto, providing 2 values. Up to 4 values can be provided.

* ''aParseTree'' '''valueWithX:''' ''valueOfX'' shortcut provided, since 'x' is such a common name.

* ''aParseTree'' '''simplify''' simplifies a parsed formula (if possible)

* ''aParseTree'' '''derivate''' generates a derivate

=== Formula Examples ===
vars := Dictionary new.
vars at:'a' put:10.
vars at:'b' put:20.
vars at:'c' put:30.
(Physic::Parser parse:'a*x^2 + b*x + c') valueIn:vars
=> 10·x·x + 20·x + 30. (still a symbolic expression, because 'x' is unknown)

vars := Dictionary new.
vars at:'a' put:10.
vars at:'b' put:20.
vars at:'c' put:30.
vars at:'x' put:1.
(Physic::Parser parse:'a*x^2 + b*x + c') valueIn:vars
=> 60 (a number)

"/ alternative (an inline object instead of a Dictionary)
vars := { a: 10 . b: 20 . c: 30 . x : 2 }.
(Physic::Parser parse:'a*x^2 + b*x + c') valueIn:vars
=> 110 (a number)

"/ alternative (individual values (up to 4 associations))
('a*x^2 + b*x + c' asPhysicExpression)
valueWith:('a' -> 10)
with:('b' -> 20)
with:('c' -> 30)
with:('x' -> 2).
=> 110 (a number)

('3*x^2 + 5*x + 17' asPhysicExpression) valueWithX:5
=> 117

('a*x^2 + b*x + c' asPhysicExpression) derivate
=> 2·a·x + b

('sin(a*x) + cos(b*x)' asPhysicExpression) derivate
=> cos(a·x)·a - sin(b·x)·b

== Equation Solving ==

The solver can solve simple equations (but do not expect it to be a replacement for Mathematica ;-):

equation := 'a = 5*b + c' asPhysicExpression.
equation solveFor:'b'
=> b = (a - c) / 5
(actually, it will give "b = (1/5)·(a - c)", which is equivalent)

For example, from the wellknown Formula "U = R * I",
equation := Physic::Parser parse:'U = R * I'.
we can derive:
equation2 := equation solveFor:'R'.
and get "R = U/I". Of which the right side:
formulaForR := equation2 rightSide
=> U/I

Applying this formulaForR to concrete values:
formulaForR valueIn:{ 'U' -> 5 volt . 'I' -> 20 milliAmpere }
=> 250 Ω

== Providing additional Formulas ==

The framework's knowledge database about units is defined by a set of formulas, from which result units are determined, when arithmetic operations are performed on physical values.

This set of default formulas can be retrieved via "<code>PhysicalUnit formulaStrings</code>".

Notice: we have included those formulas in the framework, so no internet access is required for these operations. Otherwise, operation in isolated networks (test labs) would be made impossible.

You can add more knowledge by:
Physic::PhysicalUnit '''addFormula:''' ''formulaString''

As a concrete example, the Momentum (which is Energy * Time) is predefined via:
PhysicalUnit addFormula:'Momentum = Energy * Time'
the names in the formula must correspond to the unit names;
if new units are to be made well known, it must be defined via:
Physic::PhysicalUnit addKnownUnit:aUnit
or
Physic::PhysicalUnit addKnownUnit:aUnit as:nameInFormula

== Nature Constants ==

The following constants (see [https://en.wikipedia.org/wiki/International_System_of_Units#Definition]) are known to the parser and can be used in formula/equations. They can also be accessed by elementary code via the global variable "<code>Physic::NatureConstants</code>" by index messages (i.e. "at:''name''" , "[''name'']" or simply name). The values have been taken from public available data (such as Wikipedia). Some of them are measured or estimated values, which might have changed slightly by the time you read this (see below on how to update the facts database).

==== Fundamental Constants ====
BoltzmannConstant => 1.380649e-23 J/K
AvogadroConstant => 02214076e+23 1/mol
ElectronCharge => -1.602176634e-19 C
ElectronVolt => 1.602176634e-19 J
PlanckConstant => 6.62607015e-34 Js
PlanckTime => 5.391247e-44 s
PlanckMass => 21.76434 µg
PlanckLength => 1.616255e-35 m
LightSpeed => 299792.458 km/s
SoundSpeed => 343 m/s
GravitationalConstant => 6.6743e-11 m³/(kg·s²)
CoulombConstant => 8987551782 kg·m³/(s²·C²)
VacuumPermittivity => 8.8541878188e-12 s⁴·A²/(m³·kg)
VacuumPermeability => 1.25663706212e-06 H/m
MolarGasConstant => 8.31446261815324 J/(mol·K)

or by their aliases:
LightSpeed c
PlanckConstant h , ℎ (#8462)
ReducedPlanckConstant hbar, ℏ (#8463)
GravitationalConstant G
VacuumPermittivity ε0 , epsilon_0
VacuumPermeability μ0 , mu_0
ElectronCharge e

For example:
Physic::NatureConstants at:'GravitationalConstant'
=> 6.6743e-11 m³/(kg·s²)
Physic::NatureConstants['GravitationalConstant']
=> 6.6743e-11 m³/(kg·s²)
Physic::NatureConstants GravitationalConstant
=> 6.6743e-11 m³/(kg·s²)
Physic::NatureConstants G
=> 6.6743e-11 m³/(kg·s²)
or:
Physic::NatureConstants at:'LightSpeed'
=> 299792.458 km/s

Physic::NatureConstants ElectronCharge
=> -1.602176634e-19 C

Physic::NatureConstants e
=> -1.602176634e-19 C

==== Elements ====

atom => database with facts about atoms
atom[X], for X in {'H','He','Na','Li','C','N','O','Au',...}.
provides data for 'name', 'symbol', 'atomNr', 'atomWeight', 'meltingTemperature', 'boilingTemperature', 'protons', 'neutrons', 'density', etc. For example:
Physic::NatureConstants['atom']
=> dictionary indexed by atom symbol

Physic::NatureConstants['atom']['H']
=> {"name":"Hydrogen","symbol":"H","atomNr":1,"atomWeight":...}
dictionary of attributes of hydrogen

Physic::NatureConstants['atom']['He']['atomWeight']
=> 4.002602 amu (atomWeight of helium)

Physic::NatureConstants['atom']['Li']['density']
=> 534.0 kg/m³ (density of lithium)

Physic::NatureConstants['atom']['Cu']['specificResistance']
=> 1.68e-08 Ω/m (specific electric resistency of copper)

spoiler: access via messages is also possible:
carbon := Physic::NatureConstants['atom']['C'].
carbon atomWeight
=> 12 amu

Physic::NatureConstants atom Cu specificResistance
=> 1.68e-08 Ω/m (specific electric resistency of copper)

The builtin database is incomplete; you may want to fill in missing data in an initialization action, as described below. To see the information as present in your system, evaluate (in a workspace):
<code>(Physic::NatureConstants['atom']) inspect</code>.
and fill in values with:
<code>Physic::NatureConstants['atom']['Cu']['soundSpeed'] := 3570 meter / 1 seconds</code>.

==== Astronomic Data ====
astronomicalObjects[X], for X in {'earth', 'moon', 'sun', 'mercury', 'venus', 'mars', 'jupiter', 'saturn', 'neptune', 'uranus', 'pluto' }
'planets' is an alias.
Both provide planetary data: mass, radiusMean, volume, aphelion, perihelion, escapeVelocity.

For example, <code>Physic::NatureConstants['planets']['venus']['mass']</code>.

Physic::NatureConstants['astronomicalObjects']
=> dictionary indexed by name

Physic::NatureConstants['astronomicalObjects']['mars']
=> dictionary of attributes of mars

Physic::NatureConstants['astronomicalObjects']['venus']['mass']
=> mass of venus

other useful constants are:
DISTANCE_SUN_EARTH
DISTANCE_EARTH_MOON
AstronomicalUnit
EarthGravity
earth, moon, sun, mercury, venus, mars, jupiter, saturn, uranus, neptune, pluto
mass[X], for X in planet-names
volume[X], for X in planet-names
radius[X], for X in planet-names

Physic::NatureConstants['planets']['earth']['mass']
Physic::NatureConstants['planets']['earth']['massWater']
Physic::NatureConstants['planets']['earth']['massAtmosphere']
Physic::NatureConstants['planets']['earth']['surface']
Physic::NatureConstants['planets']['earth']['surfaceLand']
Physic::NatureConstants['planets']['earth']['surfaceWater']

Examples:
Physic::NatureConstants['planets']['sun']['mass'] => 1.9885e+30 kg
Physic::NatureConstants['planets']['sun']['volume'] => 1.41e+18 km³
Physic::NatureConstants['planets']['earth']['mass'] => 108.321 km³

==== Filling the Facts Database ====
The database as deployed obviously cannot provide any possible useful value for your particular application. The current set is provided for examples and only contains knowledge which is often used in physics, some chemistry and mechanical applications.

If you expect more builtin data, please let us know.
If you find inexact values or wrong values due to typing errors, or if new scientific research data is available, also.

In any case, you can fill or fix the database yourself with both missing, inexact or wrong values:
Physic::NatureConstants constants[''name''] := ''newValue''
or (the equivalent):
Physic::NatureConstants constants at:''name'' put:''newValue''

For example, to add data for an atom, you could write:
goldInfo := Physic::NatureConstants['atom']['AU'].
goldInfo['meltingTemperature'] := 1337.33 kelvin.

You can also add completely new domain specific data. For example, if your machines process wood and the densities are required in your drilling setup, you may want to execute:
woodData := Dictionary forCaseInsensitiveKeys.
woodData['walnut'] := { density: 650 kiloGram / 1 cubicMeter }.
woodData['mahogany'] := { density: 600 kiloGram / 1 cubicMeter }.
woodData['maple'] := { density: 700 kiloGram / 1 cubicMeter }.
woodData['oak'] := { density: 770 kiloGram / 1 cubicMeter }.
woodData['rosewood'] := { density: 840 kiloGram / 1 cubicMeter }.
woodData['cherry'] := { density: 7400 kiloGram / 1 cubicMeter }.
woodData['balsa'] := { density: 120 kiloGram / 1 cubicMeter }.
Physic::NatureConstants['wood'] := woodData.
then use in your code:
Physic::NatureConstants['wood']['çherry']['density']

Notice that these numbers are just examples; the actual densities vary much and also depend on dryness and other factors.

==== Examples Involving Constants ====
In Smalltalk (accessing the constants directly):
Physic::NatureConstants['speed']['sound']
Physic::NatureConstants['planets']['venus']
Physic::NatureConstants['planets']['mars']['mass']

1.0 kiloGram * (Physic::NatureConstants['LightSpeed']) squared
=> 89875.51 TJ

In JavaScript:
Physic::NatureConstants['speed']['sound']

In Smalltalk (using the Math language parser):
Physic::Parser evaluate:'1 kg * LightSpeedˆ2'.
Physic::Parser evaluate:'1 kg * LightSpeed²'
Physic::Parser evaluate:'mass[sun] * mass[earth] / earth[perihelion]ˆ2'.

In Math language:
1 kg * LightSpeedˆ2
GraviationalConstant * mass[sun] * mass[earth] / earth[perihelion]²

== Measured Physical Values ==
You can combine physical values and measurement values to keep track of errors in computations.

Example: Assuming, that your cheap 10% accurate voltmeter measured 10 volts, this could be written as:
u := (10 volt ±% 10).
and if that voltage was measured across a cheap 100 ohm resistor with 5% precision,
r := (100.0 ohm ±% 5).
the current will be:
i := u / r.
which is:
(MeasurementValue value:100.0 minValue:85.7 maxValue:115.8) mA
and its min/max/expected values can be extracted with:
i minValue => 84.7 mA
i maxValue => 115.8 mA
i expectedValue => 100 mA
i relativeError => 0.15
or nicer:
i minValue asMilliAmperes roundedToScale:2 => 84.71 mA
i maxValue asMilliAmperes roundedToScale:2 => 115.79 mA
i expectedValue asMilliAmperes roundedToScale:2 => 100 mA

Notice: currently, you cannot take the plain minValue/maxValue and round them, as these are kept in baseUnits internally, which would round to 1/100 ampere instead of 1/100 milliampere. Therefore, the values are first forced into milliAmperes so that the rounding is what we want.

== Physical Values and Numeric Precision ==
Physical values will use the underlying number type when computing new values. For example,
10 volt / 3 ampere => (10/3) ohm
generates a fractional Ohm value *whis is exact), whereas:
10.0 volt / 3 ampere => 3.33333 ohm
returns a float value (which is an approximation).

It is usually a good idea to start with float values, and scale to the desired precision output when printing. Typically floats are used in the engineering domains, where measurements with error tolerances are involved. If your measurement and components have an error in the percent range, there is no need to compute exact or with a precision in the 10e-50 range.

Please refer to the "[[Numeric_Limits/en|Numeric Limits]]" document for more details on number types.

== Printing Physical Values ==
The printing of the amount depends on the underlying number representation.
As shown previously, this can be a Fraction, a Float, an Integer or any other number subtype, depending on the values from which it was computed/constructed.

For convenient printing, fractions are usually not wanted; you can either convert the amount to a scaledDecimal when creating the value,
or convert the value afterwards.
ScaledDecimals print the value rounded to a given number of digits, but use the full internal precision for computations.

For example:
(1/3) printString => '(1/3)'
(1/3) asFloat printString => '0.333333333333333'
((1/3) asScaledDecimal:2) printString => '0.33'
((1/3) asFixedDecimal:2) printString => '0.33'

(2/3) printString => '(2/3)'
(2/3) asFloat printString => '0.666666666666667'
((2/3) asScaledDecimal:2) printString => '0.67'
((2/3) asFixedDecimal:2) printString => '0.67'

However:
((1/3) + (1/3)) printString => '(2/3)'
((1/3) asFloat + (1/3) asFloat) printString => '0.666666666666667'
( ((1/3) asScaledDecimal:2) + ((1/3) asScaledDecimal:2)) printString => '0.67'
( ((1/3) asFixedDecimal:2) + ((1/3) asFixedDecimal:2)) printString => '0.66'

Notice the difference between scaledDecimals (which compute exact values),
and fixedDecimals (which compute with the printed values).
Only use fixedDecimals for monetary tables, where the sums of the printed numbers should sum up correctly.

So, to print a length value of 15mm, the following can be used:
15 milliMeter => 15 mm
15 milliMeter as:'Meter' => (3/200) m
15 milliMeter as:'m' => (3/200) m
15.0 milliMeter as:'m' => 0.015 m
15.0 milliMeter as:'cm' => 1.5 cm

(15 milliMeter as:'m') asScaledDecimal:1 => 0.0 m
(15 milliMeter as:'m') asScaledDecimal:2 => 0.02 m
(15 milliMeter as:'m') asScaledDecimal:3 => 0.015 m
(15 milliMeter as:'m') asScaledDecimal:4 => 0.0150 m

(15 milliMeter as:'cm') asScaledDecimal:1 => 1.5 cm
(15 milliMeter as:'cm') asScaledDecimal:2 => 1.50 cm
(15 milliMeter as:'cm') asScaledDecimal:3 => 1.500 cm
(15 milliMeter as:'cm') asScaledDecimal:4 => 1.5000 cm

(15 milliMeter as:'in') asScaledDecimal:1 => 0.6 in
(15 milliMeter as:'in') asScaledDecimal:2 => 0.59 in
(15 milliMeter as:'in') asScaledDecimal:3 => 0.591 in
(15 milliMeter as:'in') asScaledDecimal:4 => 0.5906 in

== Physical Values in Activity Diagrams ==

Unfortunately, the arithmetic actions in the standard library were defined with pin types being "<CODE>Number</CODE>", instead of the more general "<CODE>ArithmeticValue</CODE>" (of which PhysicalValues inherit). Thus, they will not accept physical values if type checking is enabled on the pin values (although the underlying primitive code would handle those types).

We therefore provide a separate PhysicalValues library, with redefined arithmetic actions. Please use those when dealing with physical values (instead of "forcing" types or disabling type checks). Late note: these actions are now found in the standard library under the "Arithmetic/More Arithmetic" category.

Freeze values can be given either using the above listed instance creation messages on number (e.g. "<CODE>10 meters</CODE>" or "<CODE>1 kilo joule</CODE>") or by using a unit suffix, possibly with an appreviated SI prefix, as in "<CODE>10 kV</CODE>" or "<CODE>10 mA</CODE>".

== Physical Values as Freeze Value ==
Pins of type "PhysicalValue" accept numeric values followed by a unit symbol, such as "<code>1 kg</code>" or "<code>1 fl oz</code>", "<code>10 N</code>" or "<code>10 newton</code>".

== Physical Values in Elementary Code ==

See examples below.

== Math Language Workspace ==
You can switch the workspace (Notepad) window to accept math language syntax (instead of Smalltalk or JavaScript).

For this, open a Notepad via "''Extras''" → "''Tools''" → "''Notepad'", and choose "''Math/Physic''" in its "''Workspace''" menu1).

You can now enter math language expressions, such as:
x := 5
sin(xˆ2 + 3)
=> 0.270905788307869
or
deriv ( sin(xˆ2 + 5x), x )
=> (2·x + 5)·cos(x² + 5·x)

and evaluate them (select the text, possibly multiple lines) and click on the "PrintIt" icon or select "PrintIt" from the right-button menu. The result of the evaluation will be pasted and selected into the window, so by pressing <kbd>Delete</kbd> or <kbd>Backspace</kbd> or <kbd>CTRL-x</kbd>, it can be removed quickly.

1) Make sure that "''Autodefine as Workspace Variable''" is checked in the workspace's "''Workspace''" → "''Autodefine Variables''" menu. Otherwise assigned variables such as "x" above will only be known within one doIt.

== Examples ==

The following code snippets are plain Smalltalk code + the printed representation (as for example found in a report). For JavaScript, write "n.X()" instead of "n X" (eg. "<code>1.kiloGram() + 10.0.gram()</code>" instead of "<code>1 kiloGram + 10.0 gram</code>").

The following shows the printed output of typical Smalltalk expressions.
Notice again, that by default, the units present themself as metric SI units (eg. "1 meter" will print as meters).
To force them to print as imperial or us units, use the "asXXX" message (eg. "1 meter asFeet").

==== Length Examples: ====
{|style="width: 100%"
|-
|style="width: 50%" | (1/4) inches || => || 6.35 mm
|-
|(1/4) inches asInches|| => || 0.25 in
|-
|10 milliMeter || => || 10 mm
|-
|10 milliMeter asInches || => || 0.3937 in
|-
|10 milliMeter as:'in' || => || 0.3937 in
|-
|10 milliMeter as:'ft' || => || 0.032808 ft
|-
|10 milli meter asInches || => || 0.3937 in
|-
|10 feet || => || 3.048 m
|-
|1.8 meter asFeet || => || 5.905 ft
|-
|10 miles || => || 16.09 km
|-
|10 nauticalMiles || => || 18.52 km
|-
|1 parsec || => || 3.261563777 ly
|-
|10 kiloMeters asMeters || => || 10000 m
|-
|1 astronomicalUnits asMiles rounded || => || 92955807 mi
|-
|1 lightYears asAstronomicalUnits rounded || => || 63241 au
|-
|1000 lightYears as:(Physic::Length parsec) || => || 306.6014 pc
|-
|1 micro inch || => || 25.4 nm
|-
|1.80 meter asFeetAndInches || => || 5′10.866
|-
|1 yards || => || 0.9144 m
|-
|style="width: 70%" | e'He is {(5 foot+2 inches) asFeetAndInchesRounded}...' (1)|| => || 'He is 5′2″...'
|-
|e'He is {(5 foot+2 inches)}...' || => || 'He is 1.5748 m...'
|-
|10 centi meter|| => || 0.1 m (prints as m)
|-
|10 centiMeter|| => || 0.1 m (prints as m)
|-
|Physic::PhysicalUnit centimeter unitAmount:10|| => || 10 cm (prints as cm)
|}

1)The e'...' is a Smalltalk string with embedded expressions.

==== Velocity Examples ====

{|style="width: 100%"
|-
|style="width: 50%" | 100 miles / 1 hours || => || 44.704 m/s
|-
|style="width: 50%" | (100 miles / 1 hours) as:'mph' || => || 100 mph
|-
|style="width: 50%" | 100 kiloMeterPerHour as:'mph' || => || 62.137119 mph
|-
|style="width: 50%" | 100 milesPerHour asKiloMetersPerHour || => || 160.9344 km/h
|-
|style="width: 50%" | 1 milliMeter / 1 days || => || 11.574 nm/s
|-
|style="width: 70%" | (186282 miles+698 yard+2 feet+5 inches+(21 / 127) inches) / 1 seconds|| => || 299792.458 km/s
|-
|}

==== Mass Examples: ====
{|style="width: 100%"
|-
|style="width: 70%" | 1 kiloGram + 10.0 gram || => || 1.01 kg
|-
|(1 kiloGram + 10 gram) asGrams || => || 1010 g
|-
|10 gram || => || 10 g
|-
|10 gram asKiloGrams || => || (1/100) kg
|-
|10.0 gram asKiloGrams || => || 0.01 kg
|-
|10 gram asMilliGrams || => || 10000 mg
|-
|1 microGram || => || 1 µg
|-
|1 micro gram || => || 1 µg
|-
|10000 gram || => || 10 kg
|-
|1 pound || => || 453.59237 g
|-
|1 pound asKiloGrams || => || 0.45359237 kg
|-
|1 pound asPounds || => || 1.0 lb
|-
|1 kiloGram asPounds || => || 2.20462262184878 lb
|-
|1 atomicMassUnits asKiloGrams || => || 1.66053906892e-27 kg
|}

==== Temperature Examples: ====
{|style="width: 100%"
|-
|style="width: 50%" | 0 degreesCelsius || => || 273.16 K
|-
|style="width: 50%" | 0 degreesCelsius asFahrenheit || => || 32.018 °F
|-
|style="width: 50%" | 40 degreesFahrenheit || => || 277.59 K
|-
|style="width: 50%" | 60 degreesFahrenheit asCelsius || => || 15.556 °C
|-
|style="width: 50%" | 40 degreesFahrenheit asKelvin || => || 277.59 K
|-
|10 kelvin || => || 10 K
|-
|100 rankine || => || 55.556 K
|-
|100 rankine asRankine || => || 100.0 °R
|}

==== Energy Examples: ====
{|style="width: 100%"
|-
|style="width: 50%" | 1 joule asElectronVolts || => || 6.24150912550149E+18 eV
|-
|style="width: 50%" | 1 joule asCalories || => || 0.239005736137667 cal
|-
|style="width: 50%" | 1 joule asBTUs || => || 0.000947817 BTU
|-
|style="width: 50%" | 1.0 joule asKiloWattHours || => || 2.77777777777778E-07 kWh
|-
|10 electronVolts || => || 1.6021766208E-18 J
|-
|1 mega electronVolts asJoules || => || 1.602176634E-13 J
|-
|1000 joule asKiloWattHours || => || 0.000278 kWh
|-
|1000.0 kiloJoule asKiloWattHours || => || 0.2778 kWh
|-
|c := Physic::NatureConstants lightspeed || => || 299792.458 km/s
|-
|1 kg * c squared|| => || 89875.518 TJ (E = mc²)
|-
|(1.0 kg * c squared) asGigaWattHours|| => || 24965.42 GWh (get me some antimatter)
|-
|1 electronVolts|| => || 1.602176634e-19 J (see [https://en.wikipedia.org/wiki/Electronvolt wikipedia])
|-
|1 electronVolts / Physic::NatureConstants c squared|| => || 1.7826619216279e-36 kg (mass)
|-
|1 electronVolts / Physic::NatureConstants c|| => || 5.34428599267831e-28 kg·m/s (momentum)
|-
|1 electronVolts / Physic::NatureConstants boltzmannConstant|| => || 11604.5181215501 K (temperature)
|-
|Physic::NatureConstants hbar / 1 electronVolts || => || 6.58211956950907e-16 s (time)
|-
|Physic::NatureConstants hbar * Physic::NatureConstants c / 1 electronVolts|| => || 197.326980459302 nm (distance)
|-
|}

==== Power Examples: ====
{|style="width: 100%"
|-
|style="width: 50%"|1 kilo watt||=>||1000 W
|-
|1 imperial hp||=>||745.699871 W
|-
|1 metric hp||=>||735.49875 W
|-
|5 volt * 10 ampere||=>||50 W
|-
|1 mega watt||=>||1000 kW
|-
|70 giga watt * 10 hours||=>||2520 TJ
|}

==== Electricity Examples: ====
{|style="width: 100%"
|-
|style="width: 50%"|1 coulomb asAmpereHours||=>||0.000277 Ah
|-
|1.1 volt / 10 kilo ohm||=>||110.0 µA
|-
|100 micro farad * 10.0 volt||=>||0.001 C
|-
|100 ohm * 0.1 micro farad||=>||10.0 µs
|-
|20 milli ampere * 10 seconds||=>||(1/5) C
|-
|20.0 milli ampere * 10 seconds||=>||0.2 C
|-
|(Physic::Voltage dBu unitAmount:4) asVolts||=>||1.2277 V
|-
|'1 / (2π × √(1 farad × 1 henry))' asPhysicExpression value||=>||0.1591 Hz (from formula)
|-
|1 / (2 * Float pi * (1 farad * 1 henry) sqrt)||=>||0.1591 Hz (as Smalltalk code)
|-
|1 / (1 microFarad * 2 kiloOhm)||=>||500 Hz
|-
|100 ohm | 50.0 ohm||=>||33.33 Ω (two resistors in parallel)
|-
|Physic::ElectricResistance' colorCode:#(yellow violet red)||=>||4700 Ω
|}

==== Volume Examples: ====
{|style="width: 100%"
|-
|style="width: 50%" | 1000 liter || => || 1 m³
|-
|1000 liter asLiters || => || 1000 l
|-
|1000 liter asHectoLiters || => || 10 hl
|-
|1000 liter asCubicInches || => || 61023.744095 cuin
|-
|100.0 liter asCubicInches || => || 6102.3744095 cuin
|-
|100.0 deci liter asCubicInches || => || 610.23744095 cuin
|-
|1 liter asCubicInches || => || 61.023744095 cuin
|-
|1 deci liter asCubicInches || => || 6.1023744095 cuin
|-
|1 milli liter asCubicInches || => || 0.061023744095 cuin
|-
|1 flozGB || => || 28.4130625 ml
|-
|1 flozUS || => || 29.5735296 ml
|-
|1 flozGB asFlozUS || => || 0.960759940 US fl oz
|-
|1 flozUS asFlozGB || => || 1.040842731 imp fl oz
|-
|1 flozGB asScaledDecimal:2|| => || 28.41 ml
|-
|1 inch cubed || => || 16.387064 ml
|-
|1 inch cubed asLiters || => || 0.016387064 l
|-
|1 inch cubed asCubicInches || => || 1.0 cuin
|-
|1 inch cubed asCubicInches unitString || => || 'cuin'
|-
|1 inch cubed asCubicInches unitAmount || => || 1.0
|-
|1 inch cubed asCubicInches unitStringSI || => || 'm³'
|-
|1 inch cubed asCubicInches amount || => || 1.6387064E-05
|-
|Volume barrels unitAmount:1 || => || 1 bbl.
|-
|(Volume barrels unitAmount:1) asGallonsUS|| => ||42.0 US gal
|-
|(Volume barrels unitAmount:1) asLiters||=>||158.987295 l
|-
|Volume barrelsIMP unitAmount:1 || => || 1 bbl. Imp
|-
|(Volume barrelsIMP unitAmount:1) asLiters||=>||159.1131599 l
|}

==== Angle Examples: ====
{|style="width: 100%"
|-
|style="width: 50%" | 10 degrees|| => || 0.174533 rad
|-
|0.2 radians || => || 0.2 rad
|-
|180 degrees || => || 3.14159265358979 rad
|-
|180 degrees asDegrees || => || 180.0 °
|-
|180 degrees asDegrees asRadians || => || 3.14159265358979 rad
|-
|90 degrees asGon || => || 100 gon
|-
|gonUnit := (Physic::PhysicalUnit angle gon) || => || Gon (the unit, not a value)
|-
|gonUnit unitAmount:100 || => || 100 gon
|-
|(gonUnit unitAmount:100) asDegrees || => || 90 °
|-
|(270 degrees + 91 degrees) = 361 degrees || => || true
|}

==== Force Examples: ====
{|style="width: 100%"
|-
|style="width: 50%" | 10 newton|| => || 10 N
|-
|1 newton asGramForce || => || 101.97 gf
|-
|(Physic::Force gramForce unitAmount:50) || => || 50 gf
|-
|(Physic::Force gramForce unitAmount:50) asNewton || => || 0.4903325 N
|-
|(Physic::Force gramForce unitAmount:50) as:'N'|| => || 0.4903325 N
|-
|(Physic::Force dyne kiloUnit unitAmount:1) as:'N'|| => || 0.01 N
|-
|(Physic::Force kilo dyne unitAmount:1) as:'N'|| => || 0.01 N
|}

==== Pressure Examples: ====
{|style="width: 100%"
|-
|style="width: 50%" | 1 kilo pascal|| => || 1000 Pa
|-
|1.5 kilo pascal asTorr || => || 11.25 Torr
|-
|(Physic::Pressure torr unitAmount:11.5) asPascal|| => || 1533.207 Pa
|-
|(Physic::Pressure torr unitAmount:11.5) as:'Pa'|| => || 1533.207 Pa
|-
|((Physic::PhysicalUnit unitWithUnitString:'lbf/in²') unitAmount: 0.01933678) as:'Pa' || => || 133.322404931392 Pa
|-
|((Physic::PhysicalUnit unitWithUnitString:'lbf/in²') unitAmount: 0.01933678) as:'mmHg' || => || 1.00000013138373 mmHg
|-
|}

==== Bytes Examples: ====
{|style="width: 100%"
|-
|style="width: 50%" | 1 kilo byte|| => || 1000 byte
|-
|1 kibi byte || => || 1024 byte
|-
|100 kilo byte asKibiBytes rounded || => || 98 kiB
|-
|1 kilo byte / 1 seconds || => || 1000 B/s
|-
|1 kilo byte / 1 seconds * 5 minutes || => || 300 kB
|-
|1 mega bits / 2 seconds || => || 500000 b/s
|}

==== Misc Other Examples: ====

{|style="width: 100%"
|-
|style="width: 50%" | 10 candela / 1 square meter || => || 10 lx
|}

=== Other (Fun) Examples: ===
===== Planet Distance =====
what is the smallest possible distance between earth and mars
 (See also: google for "smallest distance earth mars"):
|earth mars minDistMarsSun maxDistEarthSun|

earth := Physic::NatureConstants['planets']['earth'].
mars := Physic::NatureConstants['planets']['mars'].
minDistMarsSun := mars['perihelion']. "/ [https://en.wikipedia.org/wiki/Orbit_of_Mars See: "Orbit of Mars"]
"/ perihelion is the smallest distance from the sun
maxDistEarthSun := earth['aphelion']. "/ [https://en.wikipedia.org/wiki/Earth%27s_orbit See: "Orbit of Earth"]
"/ aphelion is the largest distance from the sun

minDistMarsSun - maxDistEarthSun
=> 54600000km (54.6 mio km)

===== Electric Force / Coulomb's Law =====
the force between two electrons at 1m distance:
q := Physic::NatureConstants['ElementaryCharge']. "/ is: [https://en.wikipedia.org/wiki/Elementary_charge 1.60217663 × 10-19 C]
k := Physic::NatureConstants['CoulombConstant']. "/ is: [https://en.wikipedia.org/wiki/Coulomb_constant 8987551792.3 kg·m³/(s²·C²)]
r := 1 meter.
f := k * q squared / r squared.
=> 2.31e-28 N

== References ==

 [https://en.wikipedia.org/wiki/International_System_of_Units International System of Units (SI)]
 [https://en.wikipedia.org/wiki/United_States_customary_units US Customary Units]
 [https://en.wikipedia.org/wiki/Centimetre%E2%80%93gram%E2%80%93second_system_of_units CGS System]
 [https://en.wikipedia.org/wiki/Avoirdupois Avoirdupois]
 [https://en.wikipedia.org/wiki/Troy_weight Troy Weight]
 [https://en.wikipedia.org/wiki/Imperial_units Imperial Units]

UsageHints/en

2026-02-23T11:30:07Z

Sv: Änderung übernommen aus altem Wiki von cg, 29.11.25

== Introduction ==
Expecco contains a number of features which might be different or unknown to other UI frameworks,
but which are nevertheless very useful to know.

== General Layout ==
[[Bild:Expecco General Layout1.png|thumb|300px|Expecco showing a new project (nothing selected in the tree). The left part shows the project tree, the right part the editor (here none)]]
[[Bild:Expecco General Layout2.png|thumb|300px|Expecco with an action item selected. The right part now shows the item editor]]

Expecco is a multi-Window and multi-Tab Application: you can open multiple main windows (via the ''"Window"'' menu) and work within the same project or in multiple projects at the same time. Each such main window presents one project. However, if two main windows are opened on the same project, they will monitor each other and update themself as required. If you started to modify an item in one window, the other will switch to "read only" mode, and update its contents once you accepted the change in the first window.

Each main window is organized under a variable number of tabs, each presenting a selected item from the project (i.e. a test plan, activity, action or attachment).

Each tab consists of two major parts: a project tree on the left, and an edit area at the right. The editor is specific to the kind of object being selected.

Most often used editors are:
* Test plan editor: arranges actions into a sequence of test cases (which are actions)
* [[CompoundBlock_Editor-CompoundWorksheet_Editor/en|Compound action editor]]: to edit actions defined by an activity diagram
* [[Attachment_Editor/en|Attachment editor]]: to edit the contents of test data

== Dual Use of the Tree ==
The tree has different behavior on Click vs. Press-and-Move.
* A click selects the element for editing;
* a press-and-move initiates a drag operation to copy or move the selected element to somewhere else (either another position inside the same tree or to another tree, or into a diagram as an action step, or into a test plan as test case).

This behavior may be hindering, if you want to drag and drop actions from the tree.
For this, open a separate tree, which is used exclusively for drag&drop (click on the split-tree button above the tree).

It should be noted, that once you are more experienced, you will probably no longer drag&drop from the tree, but instead press <kbd>CTRL-n</kbd> in the editor, to place actions via a dialog, or press <kbd>CTRL-c</kbd> <kbd>CTRL-v</kbd> to copy-paste it.

== Menus and Toolbars with Delayed Menus ==
Some menu funtions show a list of choices, if you click it and wait for a while (keeping the mouse button or touchpad fingers down).

Such menus items are displayed with a ''greyish'' or lighter down-arrow beside, as for example in this toolbar menu item:
[[Datei:Menu Back button.png]]

Often a list of previous items or other history is presented by this so called "''delayed menu''".

* If you press and hold, the sub menu will appear after a short delay.
* If you just click, without waiting for a menu to appear, the default action will be executed.
* If you click on the arrow, the sub menu will appear immediately.

== Menus and Toolbars with Regular Submenus ==
These are displayed with a ''blackish'' or darker arrow beside them. The menu will drop down immediately.

== Toolbar Items which Remember the Last Choice (Quickmenus) ==
[[Bild:Expecco General QuickMenu1.png|thumb|150px|Quickmenu: button before]]
[[Bild:Expecco General QuickMenu2.png|thumb|150px|Quickmenu: Selecting an item]]
[[Bild:Expecco General QuickMenu3.png|thumb|150px|Quickmenu: button afterwards]]
The item-creation toolbar items above the left tree will remember your last choice, and keep that as default action.
These items are of the above described "''delayed-menu''" type,
and will change their image to reflect the previous action's choice. This will be the action performed if you click and release quickly.

== Resize Handles (between Sub Panes) ==
Depending on your view style setting, these handles may only show up while the mouse pointer is hovering over it.
Some of them are shown with a single arrow (above and below the ''gritty rubber area'', and others are shown with arrows pointing in opposite directions.

If you press-and-hold the mouse button in the center area, these handles behave as known in other UI frameworks: just drag and resize the views underneath.

If you click on one of the arrows, the views' sizes will change to full size towards the arrow. As mentioned above, some only present the fullsize-option on one side.

If one of the views is currently being resized to full size, a single click on the center (not a press-and-move) will restore the previous size, whereas a press-and-move on the handle acts as normal.

== F8: Again in the Text Editor ==
<kbd>F8</kbd> is a shortcut for the "''Again''" keyboard function, which repeats your last text edit operation. Be it a delete, replace, or search-and-replace.
A very powerful operation. In the popup menu, you'll also find ''"Again for All"'', which repeats the operation until no more matches are found (eg. to replace or cut all occurrences of a word)

== CTRL-V: Paste History in the Text Editor ==
In addition to the common paste operation (<kbd>CTRL-v</kbd> unshifted) which pastes the last copy- or cut text,
expecco keeps a history of previous copy/cut texts. Press <kbd>CTRL-V</kbd> (both SHIFT and CTRL pressed) to get a dialog from which you select the text to be pasted.

== CTRL-O: Toggle between Overwrite and Insert Mode in the Text Editor ==
The title already says it: enter <kbd>CTRL-O</kbd> (both SHIFT and CTRL pressed) to switch to overwrite mode and back. By default, text editors will insert the characters you type. There is also a little indicator showing "I" or "O" at the bottom right. The indicator also has a popup menu for more options.

== Speed Scroll ==
The faster you move on a touchpad, the faster will it scroll.

== Horizontal Scroll with the Mouse Wheel ==
Hold the <kbd>SHIFT</kbd> or <kbd>CMD</kbd> key.

== Pagewise Scroll and Jump Scroll ==
In a scrollbar, click below or above the so-called thumb for pagewise scrolling. This is an autorepeat operation (keep the mouse button pressed).

Shift-click for absolute positioning.

In a textview, press <kbd>CTRL-g</kbd> to scroll to an absolute or relative line number.

== Zoom In/Out with the Mouse Wheel ==
Hold the <kbd>CTRL</kbd> key.

== Info Messages at the Bottom ==
Some info messages at the bottom disappear after some time.
 The popup menu item "''Previous Masseges''" brings them back (right click in the info message area) .

== Use the Action Finder ==
[[Bild:Expecco General ActionFinder1.png|thumb|250px|Action Finder: Searching for a String Splitter by Name/Tag...]]
[[Bild:Expecco General ActionFinder2.png|thumb|250px|Action Finder: Searching for a String Splitter by Input & Output...]]
If you need an action to perform some string or numeric operation,
but do not know if such a function is found in the standard library,
and where it might be, perform the following steps:

: in the diagram editor, press <kbd>CTRL-n</kbd> (i.e. "''New Step''");
:: first try a name search, providing one or more keywords (separated by commas).
:: use obvious words, such as "string", "plus", "split", "arithmetic", "concat" etc.
: if there is nothing which seems to fit,
:: click on "''Search by Result''" to open the Action Finder
:: enter an example set of input values and the desired result and click on "''Search''".
: if you are lucky, there is such an action, and you can click on "''New Step''" in the finder.
: Or it finds a textual code sequence to compute that result, and offers you to generate a new elementary action for it.

More on the Action Finder is found [[Action_Finder/en|here]].


== Use the File Browser ==
Expecco includes a number of useful tools which are actually part of the underlying IDE (Smalltalk/X, on which expecco is based, and which is part of the application).
The tools are found in the "''Extras''" → "''Tools''" menu, and one of those tools is the so called "'File Browser''".
You can use this tool as text editor, file finder or file comparator.
 More on the File Browser is found [[File_Browser|here]].

File Browser

2026-02-23T11:26:35Z

Sv: Änderung übernommen aus altem Wiki von cg, 29.11.25

== Introduction ==

Bundled with expecco comes a tool called "''File Browser''", which can be used for typical day-to-day tasks related to file and directory management. It is operating system independent and works the same on all supported platforms.

It can be opened via "''Extras''" → "''Tools''" → "''File Browser In...''". Also some popup menus offer an entry to open a File Browser (eg. a text view, in its "''Others''" → "''Tools''" → "''Open File Browser on It''") when a valid filename is selected, or a freeze value of a step in an activity diagram)

The browser contains sophisticated search functions (by name, size, access time or contents), file difference viewer, duplicate file finder, bulk rename, deep copy or remove and other useful functions.

It also includes a hex dump view, an image viewer for the most popular graphics formats (TIFF, GIF, PNG, JPEG and many others), a simple HTML viewer, an XML structure viewer and support for ctags for easy navigation inside source code files.

The file browser is derived from the standard Smalltalk/X file browser, which is described in the [http://live.exept.de/doc/online/english/tools/TOP.html Smalltalk/X online documentation].

== Editors ==
A double click on a file will present the file's contents in a filetype specific editor.

=== XML Files ===
The XML file is parsed and a DOM tree is presented. This also includes an xpath entry field to locate elements within the document.

=== HTML Files ===
A preview (not supporting style sheets or Javascript) is presented.

=== Source Code ===
For some common programming languages, a tag list is shown at the right, to quickly navigate to individual fuctions within the text.
However, be aware that it is not meant as a replacement for power editors or IDEs.

=== Images ===
If the file contains a bitmap image (JPG, PNG, GIF, TIFF, and many other formats),
the picture is shown in the lower area, and the area's own toolbar offers a bitmap editor to be opened on it.
Be aware that this editor's main task is to edit icons; i.e. small bitmaps.
It is not meant as a replacement for powerful image editor like gimp.

=== Archives ===
Tar and zip archives are supported and the contents is listed. In addition, extraction or the preview of individual files is offered.

== Utility Functions ==
== Searching ==
Click
[[Datei:SearchButton.png|search button]] to open the search tool in the lower area,
which offers a file-search utility with various filters and options. Files can be searched by size (eg. find files larger than a given size), by modification time, by contents (includes a string, does not include a string). Also, duplicate files can be found quickly.

=== Opening from a Text Editor ===
Code editors, document editors and many other text editors provide an open-menu item, as shown in the following screenshot: [[Datei:FileBrowserOpenInTextView.png|300px]] 
Notice, that the menu item is only enabled if the selection represents a filename.

=== Opening via the Freeze Value's Menu ===
If an input/output pin with a type of "Filename" and it has a freeze value, the popup menu contains an "Open FileBrowser" item. 
[[Datei:FileBrowserOpenFromFreezeValue.png|200px]]
 

=== Opening via the Activitylog ===
If an input/output pin's value represents a filename, the pop up menu also provides this function.
 
[[Datei:FileBrowserOpenViaActivityLog.png|300px]]

Personal Settings/en

2026-02-23T11:24:58Z

Sv: Änderung übernommen aus altem Wiki von cg, 29.11.25

= Personal Settings =
All of your personal settings are stored in a settings file, which is loaded upon startup.
By default, the file is stored in "<code>~/.expecco/.expeccoSettings</code>", where "<code>~</code>" (tilde) is your home folder on Unix/Linux/macOS systems, or the personal documents folder on Windows systems. The actual path is shown in the setting dialog's top page.

It is possible to use different settings by starting expecco with a "<code>--settings <filename></code>" [[Command_Line Options#Command_Line|command line argument]].

The settings dialog is opened via the "''Extras''" → "''Settings''" item in the main menu, and contains an index on the left, and individual settings editors as per selection on the right.

Notice that changes in the settings dialog will only affect your current expecco session, unless saved via the "''Save Settings''" button (you will be asked when the dialog is closed).

== Find a Settings Value by Name ==
The settings dialog's menu contains an entry named "''Show Search Field''", which adds a textfield, into which you can type a keyword.
Then, all places where this keyword is encountered in either the label or its tooltip will be highlighted. For example, if you want to locate all places which relate to "code" settings, try searching for "code".

== Settings You May Want to Change ==

==== User interface language (English, German, French, ...) ====
By default, expecco uses the language as defined in the operating system's environment (i.e. $LANG shell variable or Windows setting). This can be overridden via the "''Language''" dialog. All language translation texts are present in external language files (found in the installation folder's "resources/exept/expecco" subfolder, and missing translations can be provided by exept via updates or even added/changed by yourself (if required).

==== External Tools ====
Here, paths to external tools (such as "ruby", "node.js" or "gnuplot") can be redefined. By default, expecco assumes that those commands are found along your shell's PATH setting.Also, the access method (http or https) for the online documentation is defined here. This will be used when clicking on a help button or selecting a help item from the menu.

==== Automatic or Semiautomatic Updates & Patches ====
Expecco can be configured to automatically look for and optionally install updates and/or patches from the exept update server (<code>http://download.exept.de/download/expecco</code>). Depending on your network configuration (firewalls or even totally isolated test-labs), access to this public server may or may not be possible on your machine. Then, updates can be either installed via files (which can be transported eg. via an USB stick) or by another expecco, which gets the updates via file and provides the update service for other machines inside your network. In this later setup, you'll have to manually transport the files only once (to the update service providing machine) and configure the other machines to fetch the updates from that master expecco machine.

== Individual Settings Editors ==

The individual settings editors are further described in:

* [[Settings LanguageSettings/en|Language Settings]]
* [[Settings PrinterSettings/en|Printer Settings]]
* LookAndFeel Settings
** [[Settings TreeSettings/en|Tree Settings]]
** [[Settings CodeEditorSettings/en|Code Editor Settings]]
*** [[Settings SyntaxColorSettings/en|Syntax Color Settings]]
** Diagram Editor Settings
*** [[Settings GeneralWorksheetEditorLookSettings/en|General Worksheet Editor Look Settings]]
*** [[Settings WorksheetEditorElementLookSettings/en|Worksheet Editor Element Look Settings]]
** [[Settings TableDrivenBlock/en|Table Driven Block Settings]]
** [[Settings TagColorSettings/en|Tag Color Settings]]
** [[Settings TagIconSettings/en|Tag Icon Settings]]
** [[Settings StateColorSettings/en|State Color Settings]]
** [[Settings SoundSettings/en|Sound Settings]]
** [[Settings FontSettings/en|Font Settings]]
** [[Settings HotKeySettings/en|HotKey Settings]]
** [[Settings MiscLookSettings/en|MiscLook Settings]]
* [[Settings ProjectManagementSettings/en|Project Management Settings]]
** [[Settings ExpeccoNETSettings/en|Expecco ALM Settings]]
* [[Settings ExecutionSettings/en|Execution Settings]]
** [[Settings ExternalScriptInterpreterSettings/en|External Script Interpreter Settings]]
* [[Settings LoggingSettings/en|Logging Settings]]
** [[Settings DebuggerSettings/en|Debugger Settings]]
** [[Settings ReportSettings/en|Report Settings]]
* [[Settings StandardReportTemplateSettings/en|Standard Report Template Settings]]
** [[Settings CompanySettings/en|Company Settings]]
* [[Settings ExternalToolsSettings/en|External Tools Settings]]
* [[Settings UpdatesSettings/en|Updates Settings]]
* [[Settings PluginSettings/en|Plugin Settings]]
** [[Settings CommonJavaGUITestPluginSettings/en|Common Java GUI Test Plugin Settings]]
** [[Settings GUITestPlatformSettings/en|GUI Test Platform Settings]]
** [[Settings GembirdPluginSettings/en|Gembird Plugin Settings]]
** [[Settings JIRAPluginSettings/en|JIRA Plugin Settings]]
** [[Settings JavaBridgePluginSettings/en|Java Bridge Plugin Settings]]
** [[Settings ManualTestImport1PluginSettings/en|Manual Test Import1Plugin Settings]]
** [[Settings ManualTestImport2PluginSettings/en|Manual Test Import2Plugin Settings]]
** [[Settings MobileTestingSettings/en|Mobile Testing Plugin Settings]]
** [[Settings OpenETSGuiTestingPluginSettings/en|OpenETS GUI Testing Plugin Settings]]
** [[Settings PolarionPluginSettings/en|Polarion Plugin Settings]]
** [[Settings SAPPluginSettings/en|SAP Plugin Settings]]
** [[Settings SeppMedPluginSettings/en|Sepp.med Plugin Settings]]
** [[Settings VisualBasicScriptSettings/en|VisualBasic Scripting Settings]]
** [[Settings SeleniumSettings/en|Webtest Plugin Settings]] (Selenium)
** [[Settings WindowsAutomationPluginSettings/en|Windows Automation Plugin Settings]]
** [[Settings XMImportPluginSettings/en|XMImport Plugin Settings]]
* [[Settings LicenseInstallation/en|License Installation]]

[[Category: Incomplete]]

Settings ExternalScriptInterpreters Shell and BatchSettings/en

2026-02-23T11:23:00Z

Sv:

== Shell and Batch Settings ==

[[Datei:ShellAndBatchSettings.png|mini]]

=== Shell Path ===
Usually only needed under Windows, if you have installed a Unix-shell interpreter.
Only needed if your suite contains shell-script actions.

=== Powershell Path ===
For powershell actions. Powershell is usually already installed under Windows, but available for Unix/Linux as well.

 
----

[[Settings_ExternalScriptInterpreters_GroovyClassPathSettings/en|Next (Groovy Settings)]]

[[Settings_ExternalScriptInterpreterSettings/en|Back to "External Script Interpreter Settings"]]
 
[[Settings/en|Back to the main page "Settings"]]

[[Category:Settings]]

Settings ExternalScriptInterpreters NodeSettings/en

2026-02-23T11:20:43Z

Sv: Änderung übernommen aus altem Wiki von cg, 29.11.25

== Groovy Class Path Settings ==

===== Node.js Path =====

Defines the node interpreter to be used. We recommend using simply "node" and make sure that node is found along your path.

=== Execute In ===
Defines the directory in which node actions are executed.
By default, it is running inside a temporary folder, where it sees the attachments as subfolder.

 

See also [[Installing_additional_Frameworks/en#Node_Installation_.28for_Node.js_Actions.29|"Installing additional frameworks"]]

----

[[Settings_ExternalScriptInterpreters_PythonSettings/en|Next (Python Settings)]]

[[Settings_ExternalScriptInterpreterSettings/en|Back to "External Script Interpreter Settings"]]
 
[[Settings/en|Back to the main page "Settings"]]

[[Category:Settings]]

Settings ExternalScriptInterpreters GroovyClassPathSettings/en

2026-02-23T11:17:56Z

Sv: Änderung übernommen aus altem Wiki von cg, 29.11.25

== Groovy Class Path Settings ==

===== Groovy Action Blocks and ClassPath =====

Groovy actions are executed in a separate Java Virtual Machine (JVM). This JVM can be started explicitly via "[<code>Start Java on Local Machine</code>]" action blocks, via a shell script, or implicitly whenever the very first groovy action is executed.

Explicitly (i.e. manually) started JVMs can be configured via the "[<code>Add JAR</code>]" action to include any required class libraries (".jar" files),
whereas implicitly (i.e. automatically) started JVMs get their class path from the user settings.

=== Jar or Folder ===
Defines additional Jar files and paths which are passed to groovy for class resolving.

 

See also [[Installing_additional_Frameworks/en#Java_Installation_.28for_Groovy_Actions.2C_Web-_and_Mobile_Testing.29|"Installing additional frameworks"]]
----

[[Settings_ExternalScriptInterpreters_NodeSettings/en|Next (Node Settings)]]

[[Settings_ExternalScriptInterpreterSettings/en|Back to "External Script Interpreter Settings"]]
 
[[Settings/en|Back to the main page "Settings"]]

[[Category:Settings]]

Hauptseite

2026-02-23T11:13:56Z

Sv: Änderung übernommen aus altem Wiki von cg, 28.11.25

[[Hauptseite/en|English Version]]

Klicken Sie links auf ''"Letzte Änderungen"'' ("Recent changes") um die neuesten Einträge in der Dokumentation zu sehen. Sie sehen dann meist, woran unsere Entwickler gerade vornehmlich arbeiten.

<h2>expecco</h2>

<div style="display:flex; flex-wrap:wrap; padding:0; white-space:nowrap">
<div style="background-color:#ecf0fe; margin:12px 8px 0 0; flex:1 0 auto">

[[Datei:Icon_Landingpage.png|30px]]Für Einsteiger<hr>

<ul style="font-size:0.8em; padding:0.7em 1em 1em 2.4em">


<li>[https://doc.expecco.de/w2.x/index.php?title=Was_ist_expecco%3F Allgemeine Informationen]</li>
<li>[[Expecco Usecases|Einsatzbereiche]]</li>
<li>[[Features|expecco Feature-List]]</li>
<li>[[Tutorials]]</li>
<li>[[usageHints/en|Hinweise zur Bedienung]]</li>
<li>[[Glossary|Begriffserklärung]] (Glossar)</li>

<li>[[FAQ]]</li>
</ul>
</div>

<div style="background-color:#ecf0fe; margin:12px 8px 0 0; flex:1 0 auto">

[[Datei:Icon_Landingpage5.png|30px]]Installation<hr>

<ul style="font-size:0.8em; padding:0.7em 1em 1em 2.4em">
<li>[[Installation]]</li>
<li>[[Installing additional Frameworks/en| Installation zusätzlicher Tools (Node, Python, ...)]]</li>
<li>[[Personal Settings|Persönliche Einstellungen]]</li>
<li>[[Configuration & Setup|Konfiguration]]</li>
<li>[[Anbindung expecco ALM]]</li>
<li>[[SAP_Testing|Anbindung expecco an SAP]]</li>
<li>[[Spezifische Anpassung]]</li>
<li>[[expecco UI]]</li>
<li>[[Expecco_Remote_Control_App|expecco Mobile Remote App]]</li>
<li>[[Probleme & Fehler]]</li>
</ul>
</div>

<div style="background-color:#ecf0fe; margin:12px 8px 0 0; flex:1 0 auto">

[[Datei:Icon_Landingpage4.png|30px]]Werkzeuge<hr>

<ul style="font-size:0.8em; padding:0.7em 1em 1em 2.4em">
<li>[[API von Elementaraktionen]]</li>
<li>[[Debugger]]</li>
<li>[[Editoren]]</li>
<li>[[Standard Libraries/Bibliotheken]]</li>
<li>[[Weitere Werkzeuge]]</li>
<li>[[Weitere Funktionen]]</li>
</ul>
</div>

<div style="background-color:#ecf0fe; margin:12px 8px 0 0; flex:1 0 auto">

[[Datei:Icon_Landingpage6.png|30px]]Reportgenerierung<hr>

<ul style="font-size:0.8em; padding:0.7em 1em 1em 2.4em">
<li>[[Report Generation|Reportgenerierung]]</li>
<li>[[Errors during Execution|Fehler während der Ausführung]]</li>
<li>[[Secret Strings|Geheime Zeichenketten und Passwörter]]</li>
</ul>
</div>

<div style="background-color:#ecf0fe; margin:12px 8px 0 0; flex:1 0 auto">

[[Datei:Erweiterung_plugin.png|30px]]Erweiterungen (Plugins)<hr>

<ul style="font-size:0.8em; padding:0.7em 1em 1em 2.4em">
<li>[[GUI Testing]]
<ul>
<li>[[Java GUI Plugins|Java Swing/FX/SWT UI Testing]]</li>
<li>[[Mobile Testing Plugin|Mobile Testing auf Android und iOS]]</li>
<li>[[WindowsAutomation Reference 2.0|UI Testing mit der Windows Automation Library]]</li>
<li>[[Selenium_WebDriver_Plugin|Web Testing mit Selenium WebDriver]]</li>
<li>[[VNC_Plugin_Reference|VNC UI Testing]]</li>
<li>[[GUI Testing|Weitere GUI Testing Plugins]]</li>
</ul>
</li>
<li>[[Schnittstellen zum SUT]]</li>
<li>[[ManualTest]]</li>
<li>Produktivität
<ul>
<li>[[GIT Plugin]]</li>
<li>[[HG Plugin (Mercurial)]]</li>
<li>[[CVS Plugin]]</li>
<li>[[Anbindung expecco ALM | expeccoALM Schnittstelle]]</li>
</ul>
</li>
<li>[[Weitere Plugins]]</li>
</ul>
</div>

<div style="background-color:#ecf0fe; margin:12px 8px 0 0; flex:1 0 auto">

[[Datei:Icon_Landingpage3.png|30px]]Elemente der Testsuite<hr>

<ul style="font-size:0.8em; padding:0.7em 1em 1em 2.4em">
<li>[[Tree Elements|Tree Elemente]]</li>
<li>[[Folder Element|Ordner]]</li>
<li>[[Testplan Element]]</li>
<li>[[Aktionen/Aktionsblöcke]]</li>
<li>[[Datatype Element|Datentyp Element]]</li>
<li>[[Inventory Element]]</li>
<li>[[Skill Element]]</li>
<li>[[Resource Element|Ressource Element]]</li>
<li>[[Attachment Element|Anhänge]]</li>
<li>[[ReportTemplate Element|Report Templates]]</li>
</ul>
</div>

<div style="background-color:#ecf0fe; margin:12px 8px 0 0; flex:1 0 auto">

[[Datei:Icon_Landingpage3.png|30px]]API Referenz (Elementarbausteine)<hr>

<ul style="font-size:0.8em; padding:0.7em 1em 1em 2.4em">
<li>[[API von Elementaraktionen|Übersicht]]</li>
<li>[[Expecco API#JavaScript_and_Smalltalk_Elementary_Blocks|Smalltalk & JavaScript]]</li>
<li>[[Expecco API#Groovy_Elementary_Blocks|Groovy]]</li>
<li>[[Expecco_API#Node.js_.28Bridged.29_Elementary_Blocks|NodeJS]]</li>
<li>[[Expecco_API#Bridged_Python_Elementary_Blocks|Python]]</li>
<li>[[Expecco_API#Bridged_Ruby_Elementary_Blocks|Ruby]]</li>
<li>[[Expecco_API#Bridged_C_Elementary_Blocks|C]]</li>
<li>[[Expecco API#VisualBasic_Elementary_Blocks|VisualBasic ]]</li>
<li>[[Expecco Scripting API|Shell und Script Languages]]</li>
 
<li>[[Useful API Functions|Useful API Functions:]]</li>
<ul>
<li>[[Number API Functions|Number API Functions]]</li>
<li>[[String API Functions|String API Functions]]</li>
<li>[[Collection API Functions|Collection API Functions]]</li>
<li>[[Filename API Functions|Filename API Functions]]</li>
<li>[[Stream API Functions|Stream API Functions]]</li>
<li>[[Date_and_Time_API_Functions|Date & Time API Functions]]</li>
</ul>
</ul>
</div>

<div style="background-color:#ecf0fe; margin:12px 8px 0 0; flex:1 0 auto">

[[Datei:Diagramm.png|30px]]Diagramm - Elemente<hr>

<ul style="font-size:0.8em; padding:0.7em 1em 1em 2.4em">
<li>[[DiagramElements-Step|Schritt]]</li>
<li>[[Pins (Ein - Ausgänge)]]</li>
<li>[[Code Ausführung]]</li>
<li>[[DiagramElements-Connection|Verbindung]]</li>
<li>[[DiagramElements-Pin|Pin Beschreibung]]</li>
<li>[[DiagramElements-Annotation|Notiz]]</li>
<li>[[DiagramElements-Probe|Messfühler]]</li>
</ul>
</div>

<div style="background-color:#ecf0fe; margin:12px 8px 0 0; flex:1 0 auto">

[[Datei:Refresh.png|30px]]Sonstiges<hr>

<ul style="font-size:0.8em; padding:0.7em 1em 1em 2.4em">
<li>[[Release Notes 25.x]]</li>
<li>[[Release Notes 24.x]]</li>
<li>[[Release Notes 23.x]]</li>
<li>[[Release Notes 22.x]]</li>
<li>[[Release Notes 21.x]]</li>
<li>[[Release Notes 20.x]]</li>
<li>[[Release Notes 19.x]]</li>
<li>[[Release Notes 18.x]]</li>
<li>[[Release Notes 2.x]]</li>
<li>[[Release Notes 1.x]]</li>
<li>[[Future releases expecco|Zukünftige Releases]]</li>
<li>[[Smalltalk]]</li>
</ul>
</div>

<div style="background-color:#ecf0fe; margin:12px 8px 0 0; flex:1 0 auto">

[[Datei:Beispiele_icon.png|30px]]Beispiele<hr>
Sie haben Fragen, wie ein Projekt aussieht?<hr>

<ul style="font-size:0.8em; padding:0.7em 1em 1em 2.4em">
 
<li>[[Beispiele | Hier finden Sie weitere Anwendungsbeispiele.]]</li>
<li>[[Expecco Code Snippets/en | Codeschnipsel]]</li>
</ul>
</div>

<div style="background-color:#ecf0fe; margin:12px 8px 0 0; flex:1 0 auto">

[[Datei:Beispiele_icon.png|30px]]Unterstützung weiterer Qualitätsmanagement Tools<hr>

<ul style="font-size:0.8em; padding:0.7em 1em 1em 2.4em">
<li>[[Jira_Plugin_Reference|Jira]]</li>
<li>[[PolarionPlugin_Reference|Polarion]]</li>
<li>[[Aqua_Plugin_Reference|Aqua]]</li>
<li>[[Starting_expecco_via_Command_Line#Integration_with_Jenkins|Jenkins Integration]]</li>

</ul>
</div>

</div>

<h2 style="clear:left">expecco ALM</h2>

<div style="display:flex; flex-wrap:wrap; padding:0; white-space:nowrap">
<div style="background-color:#ecf0fe; margin:12px 8px 0 0; flex:1 0 auto">

[[Datei:Sonstiges-Info.png|30px]]Allgemein<hr>

<ul style="font-size:0.8em; padding:0.7em 1em 1em 2.4em">
<li>[[Was ist expecco ALM?]]</li>
<li>[[Was ist der expecco Lizenzserver?]]</li>
<li>[[Anbindung expecco ALM]]</li>
<li>[[Rollen und Rechte]]</li>
<li>[[Filter]]</li>
<li>[[FAQ expeccoALM/en | FAQ]]</li>
</ul>
</div>

<div style="background-color:#ecf0fe; margin:12px 8px 0 0; flex:1 0 auto">

[[Datei:Icon_Landingpage5.png|30px]]Installation/Einrichten<hr>

<ul style="font-size:0.8em; padding:0.7em 1em 1em 2.4em">
<li>[[expecco ALM Installation|Installation]]</li>
<li>[[expecco ALM Installation Patches|expecco ALM Installation Patches]]</li>
<li>[[expecco ALM Einrichten Vorgehensweise|expecco ALM Einrichten]]</li>
<li>[[expecco ALM expecco Patch Service |Patchservice für expecco]]</li>
</ul>
</div>

<div style="background-color:#ecf0fe; margin:12px 8px 0 0; flex:1 0 auto">

[[Datei:Refresh.png|30px]]Plugins<hr>

<ul style="font-size:0.8em; padding:0.7em 1em 1em 2.4em">
<li>[[AIDYMO Jira|Atlassian Jira]]</li>
<li>[[CustomerSpecific|Kundenspezifische Portale]]</li>
</ul>
</div>

<div style="background-color:#ecf0fe; margin:12px 8px 0 0; flex:1 0 auto">

[[Datei:Refresh.png|30px]]Sonstiges<hr>

<ul style="font-size:0.8em; padding:0.7em 1em 1em 2.4em">
<li>[[expecco ALM App]]</li>
<li>[[Installation Lizenzserver]]</li>
<li>[[expecco ALM Release Notes|Release Notes]]</li>
<li>[[expecco ALM Known Issues|Known Issues]]</li>
</ul>
</div>
</div>

Features

2026-02-23T11:11:46Z

Sv:

==Basissystem==

* expecco IDE
* Bibliotheken - StandardLib, ODBC, XML, uvm.
* Port Zugriff - seriell/USB/parallel/TCP
* Services - REST, SOAP, RPC, HTML, JSON, DLL-call
* Webtest - Webdriver, HTML5, Smart GWT
* Anbindung an Programmiersprachen und deren Bibliotheken
** Java/Groovy - Java Code eingeben & sofort ausführen sowie Code Injection in Java Programme
** Python - Code eingeben & sofort ausführen
** Node.js - Code eingeben & sofort ausführen
** C/C++ - Code eingeben & sofort ausführen
** Ruby - Code eingeben & sofort ausführen
** .NET - DotNET
* Diverse weitere Skriptsprachen (GNUplot, Matlab/GNUOctave, TCL, Powershell uam.)
* Manuelles/halbautomatisches/vollautomatisches Testen – benutzergeführter Testablauf
* Remotesteuerung via App unter Android, iPhone oder Webbrowser
* Report:
** Revisionssichere Testdokumentation
** Automatischer Report nach jedem Testlauf
** Individuelle Reports mit unterschiedlicher Detailtiefe generierbar
** Anpassbar an eigenes Layout
** Hinzufügen von Anhängen, Screenshots, Bildern oder Dokumenten
** Inhalt, Sprache und Erscheinungsbild an Zielgruppe anpassbar
** Mehrere Ausgabeformate möglich: PDF, HTML, XML, CSV, Text, u.v.m
** expecco Logfile mit allen Ablaufdaten, erneut ablauffähig

expecco ist modular aufgebaut – das Basissystem kann jederzeit durch unsere Plugins erweitert und an Ihren individuellen Bedarf oder an den Projektfortschritt angepasst werden. Auf Anfrage erhalten unsere Partner die Möglichkeit, eigene Plugins zu entwickeln.

Konzept:

Die Grundphilosophie von expecco ist, dass Testabläufe sowohl von Entwicklern und Programmierern, als auch von Domänenexperten und Analysten erstellt, gewartet und ausgeführt werden können, ohne daß dazu spezielle Programmierkenntnisse notwendig wären. Dabei darf es aber keine Einschränkungen geben, und ein erfahrener Nutzer hat alle Mittel zur Verfügung, um eigenen Code, Scripte und erweiterte Funktionen einzubinden oder zu erstellen.

Um beiden Anforderungen gerecht zu werden, können Abläufe in expecco sowohl als Aktivitätsdiagramm als auch als textueller code in verschiedenen Programmiersprachen definiert werden. Die ermöglicht einen "Best of both Worlds" Ansatz: einerseits können Nichtprogrammierer auf einer hohen Abstraktionsebene bestehende Aktionsbausteine mittels "Drag & Drop" oder Recording von GUI Aktionen zu komplexen Szenarien verbinden, andererseits ist es möglich, fehlende
Funktionsbausteine als Programmcode zu erstellen, und als Aktionsbaustein für andere Aktionen bereit zu stellen.

Allgemeine Features:

* Umfangreiche Standardbibliotheken
* Integrierter Rekorder
* Grafische Testentwicklung per drag&drop
* Direkt ausführbares grafisches Modell
* Laden und Speichern von Testsuiten
* Anlegen, Bearbeiten und Pflege von Testsuiten
* Testausführung
* Testentwicklung mit Singlestep, Breakpoints, Ausführung von Teilsequenzen
* Testentwicklung mit "Live changes while the system runs"
* Debugging auf hoher (Diagramm-) als auch auf niedriger (Script/Code) Ebene
* Beobachtung der Ausführung, Sammeln von Trace-, Zeit- und Logdaten
* Sammeln aller Datenflüsse, Nachrichtenpakete und Zwischenergebnisse zur späteren In-spektion
* Reportgenerierung als mensch- und maschinenlesbare Dokumente in verschiedenen Forma-ten
* Testbeschreibungen werden unmittelbar interpretiert, der Testablauf wird im Detail angezeigt und live animiert.
* Laufende Tests lassen sich anhalten, im Einzelschrittmodus ausführen und während des Ab-laufs modifizieren sowie fortsetzen.
* Flexible Parametrisierungen
* Lineare und parallele Testabläufe
* Testabläufe passen sich dynamisch an geänderte Konfigurationen an.
* Klar definierte Schnittstellen stellen sicher, dass Produktänderungen und -erweiterungen nur an einer Stelle gewartet werden müssen.
* Das integrierte Versionsmanagement sorgt für konsistente Datenhaltung
* Hohe Wiederverwendbarkeit der Testsequnzen vom Komponenten- bis zum Abnahmetest
* Import/Export von Spezifikationen
* Plattformunabhängig (Win32/64, Windows7-10; diverse Linux, MAC-OSX)

==GUI Test==
Diese Erweiterung ermöglicht das Testen bzw. Einbinden und Automatisieren von graphischen Benutzeroberflächen (GUIs). Unterstützt werden derzeit folgende Technologien:
* Java GUIs (Swing, SWT, FX)
* Microsoft GUIs (via UIA2, UIA3 - Ui Automation)
* .NET GUIs (MFC, Forms, DevExpress)
* Qt
* Mobilgeräte (Android / iPhone / iPad)
* VisualWorks Smalltalk GUIs
* VNC (remote) und lokales Display mit Bilderkennung und OCR (Texterkennung)

expecco bietet verschiedene Möglichkeiten um GUI Elemente zu identifizieren:
* Eindeutige IDs
* Eindeutige Texte
* Element-Pfad und Element-Index (XPath)
* Bilderkennung
* Absolute und relative Position

GUI Test Features:

* Nahtlose Integration in die expecco-Benutzeroberfläche
* Ein gemeinsames Werkzeug für verschiedene UI-Technologien
* Gleichzeitige Bedienung mehrerer Anwendungen
* Visualisierung des Aufbaus der Benutzeroberfläche (Komponentenstruktur)
* Informationen über verschiedene Zustände und Eigenschaften der einzelnen Bedienelemente
* Unterstützung beim Auffinden von Bedienelemente durch Hervorhebung, Vorschaubilder und "Mouse-Over" Feedback
* Filterung von passenden Aktionsblöcken aus der Block-Bibliothek abhängig von der jeweiligen UI-Technologie
* Erstellung von Testsequenzen mittels "Drag and Drop" und/oder automatischer Aufzeichnung
* Experimentelles Ausprobieren von Blöcken, Testsequenzen und Bedienelement-Pfaden
* Übernehmen von Testsequenzen in das Testprojekt

==Web Test==
Diese Erweiterung realisiert aine Schnittstelle zu WebBrowsern (Chrome, Firefox, Edge, etc) und
wird mit dem Basissystem ausgeliefert. Sie muss nicht separat Lizensiert werden.

* Selenium Webdriver, steuern und auslesen
* Unterstützt Chrome, Firefox, Edge, Opera, Safari u.a.
* HTML5, Smart GWT

Web Test Features:

* Wiedergabe/Testlauf auf allen gängigen Browser
* Ein Test auf allen Browsern ablaufbar
* Tests können „headless“ ablaufen
* Testen von Windows und Linux Anwendungen in verschiedenen Browsern
* Komfortables Zusammenstellen neuer Aktionsblöcke mit Benutzerinteraktionen
* Leichte Parameterisierung von Webformularen und automatisches Anlegen von CSV Tabellen mit Eingabewerten
* Kombination von UI-Tests mit anderen Systemen, Messgeräten, Sensoren, Datenbanken, Mobilgeräten etc.
* Messung von Antwortzeiten
* Neu-Aufnahme (rerecording) von Teilsequenzen, ohne dass die gesamte Sitzung erneut wiederholt werden muss
* Hohe Wiederverwendbarkeit von Teilsequenzen durch Herausfaktorieren von gemeinsamen Aktionen (z.B. login-Sequenzen, Formulareingaben, Tabellenprüfungen etc.)
* Lastgenerierung und Leistungsmessungen
* Das Webtest-Modul basiert auf Selenium WebDriver

==Mobile Test==
Diese Erweiterung realisiert die Anbindung an Mobilgeräte.

* Unterstützt Android und iOS

Mobile Test Features:

* Kein Jailbreak nötig
* Recording - einfache Testerstellung mit integriertem Recorder
* Fernsteuerung - einfache Steuerung der Geräte auch ortsunabhängig möglich
* Ein Test - ausführbar auf allen Geräten (Android und iOS) und Emulatoren
* Remotezugriff auf mehrere Mobiltelefone gleichzeitig
* Parallele Testausführung auf mehreren Geräten
* Kommunikation mit externer Hardware (Schnittstellen u.a.Bluetooth, NFC, WLAN, LTE, Feldbusse, Backend)
* Zugriff auf Objekte im Anwendungskontext
* Komplexität - die Testausführung erfolgt nicht nur starr linear, auch Reaktionen des Testablaufs auf Vorbedingungen und Zustandsänderungen der App sind möglich
* Parametrisierbarkeit - Eingabewerte und Geräte einfach austauschbar
* Automatisierung - Testen von bereits installierten Apps oder Apps zu Testbeginn automatisch installieren und am Ende deinstallieren
* Bausteinbibliothek - schnelle, einfache Testerstellung dank umfangreichem Vorrat an fertigen Bausteinen
* Wiederverwendbarkeit - Testschritte können für weitere Tests wiederverwendet werden
* Elementbaum inspizierbar - die Anordnung der Bedienelemente ist sichtbar, die Eigenschaften einsehbar
* Detailliertes Reporting

==Embedded Test==
Dieses Erweiterungspaket umfasst Schnittstellen zu technischen Geräten wie sie insbesondere (aber nicht nur) im Bereich Automotive typisch bedient werden.

* CAN, CANoe, CANAnalyzer, MOST,
* MQTT, SomeIP, USB,
* WSDL, REST, Remote Access,
* VNC Client, etc.

Embedded Test Features:

* mit CANoe ist expecco hier ein übergeordnetes Testwerkzeug
* Zugriff auf den von CANoe und CANalyzer implementierten COM Server
* Steuerung der Applikationen von außen
* expecco liest CANoe-Projekt aus und speichert alle Variablen in einer CSV-Datei
* Modellieren des Testablaufs
* die einmal modellierten Testabläufe können für verschiedene Steuergeräte verwendet wer-den
* das Bestücken mit Variablen erfolgt automatisiert
* Tests sind parametrisierbar
* Dynamische (parallele) Testabläufe
* Varianten: generische Testfälle für Steuergeräte Varianten können definiert warden
* Einbindung weiterer Programme und Geräte in den Testablauf: Technologieübergreifende Tests (CANoe/ Optolyzer/ Mobile Devices in 1 Testablauf)
* Testautomatisierung unabhängig von der Testumgebung (wie CANoe, National Instruments, dSpace)

==Messgeräte, Simulatoren, Schnittstellen==
Dieses Erweiterungspaket umfasst Schnittstellen zu technischen Geräten wie sie im Bereich Fabrik- und Geräteautomatisierung sowie Maschinenbau typisch benötigt werden.

* PCAN, CANUSB, Profibus, Vector Hardware Interfaces
* REST, SOAP, XML-RPC, http, https, SNMP, TELNET,
* TCP/IP, UDP, SSH, (S)FTP, DLL Calls, VISA, GPIB, SCPI, OPC UA, MQTT, SomeIP

MSS Features:

* Direktes Steuern von Hardwareschnittstellen und Bussystemen
* Steuern von Applikationen zur Kontrolle von eingebetteten Systemen
* Analoge Ein- und Ausgänge
* Vielfältige Schnittstellen ermöglichen einen End2End Test
* Dynamisches Importieren von Informationen zur Laufzeit
* Tests werden automatisiert auf Änderungen am System Under Test angepasst

==SAP==

SAP Features:

* Abbildung und Tests echter Unternehmensabläufe
* Anbindung an SAP GUI über eCATT
* Verbindung mit mehreren UIs gleichzeitig möglich

==B2B==

B2B Features:

* Edifact; Messages lesen, parsen, generieren, prüfen, verarbeiten
* Struktur/Nachrichten editor
* Swift Messages

==QM Schnittstellen==

* expecco ALM, [[Jira_Plugin_Reference|Jira]], [[PolarionPlugin_Reference|Polarion]], [[Aqua_Plugin_Reference|Aqua]], HP Quality Center, Jenkins, Seppmed-MBT suite

QM Schnittstellen Features:

* Einfache Anbindung an bereits vorhandene Test- und Qualitätsmanagementsysteme
* Remote Steuerung von expecco via SOAP/REST oder Telnet

Future releases expecco

2026-02-23T11:10:02Z

Sv: Änderung übernommen aus altem Wiki von cg, 25.11.25

== Available for Beta-Testers / Evaluation ==

* Feature: [[EDI/Edifact Plugin | EDI-Edifact]] plugin
* Feature: [[ PolarionPlugin Reference | Polarion plugin ]]
* Manual Tests: in expecco ALM

== Planned for Future Releases ==

* Compound GUI Blocks, enhanced GUI Construction Toolkit (PRO version) [-> [[MeasurementValueGUI|example]]]
* User-Constructable Control & Monitoring Window
* User-Constructable Control & Monitoring WebInterface
* Object Repository (central mapping of gui-element names - also for cross-platform tests sap)
* Enterprise Version (central database for team development)
* Manual Tests: can run in web GUI (also Android, iPad, iPhone...), control window on extra screen (Now available!)
* Manual Tests: generate original word document as report
* Expecco control window on second screen (dual screen support)
* Expecco control window in web GUI
* Separate monitor/visualisation GUI (via background action with GUI)
* More detail in modification history (both project and per block)
* Attach probe(s) to monitor views (oscilloscope and chart views)

Installing additional Frameworks/en

2026-02-23T11:07:51Z

Sv: Änderung übernommen aus altem Wiki von cg, 25.11.25

== Introduction ==
If you intent to execute actions written for Java, Node, Python, .NET, C etc.,
or to test Java-, Windows- or mobile applications, additional frameworks have to be installed on your machine.

Mostly for legal reasons, but also because you will probably want to install a most up-to-date version, we do not bundle those with the expecco installation (except for a python setup, as noted below).

Please make sure that any required framework is installed, and the commands are found by expecco
(although you will usually get a more or less descriptive warning from expecco later, if anything goes wrong. If in doubt, open the Transcript window and/or start expecco in a console window as "<code>expecco.com</code> to see any error or warning messages).

If they are already installed, but expecco fails to execute one of them, take a look at the PATH setting and/or the expecco "''Extras''" → "''Settings''" → "''Execution''" → "''External Script Interpreters''" settings. There, click on buttons labeled "?" to verify the installed version(s).

However, the recommendend setup is to only specify the command name in the settings, and ensure that the PATH variable is set correctly, to let expecco find the command via the PATH.
 The PATH should be set in your "<code>.login</code>" (Unix) or "<code>autoexec.bat</code>" (Windows) file accordingly.

== Required Frameworks Overview ==

{| class="wikitable"
|-
! Feature !! Required Framework(s)
|-
| Java/Groovy Actions || JRE (Java Runtime Environment) or: JDK (recommended)
|-
| NodeJS Actions || node
|-
| Python Actions || Python3.x (recommended) or: Python2.x (for older Python code)
|-
| Jython Actions || Java JRE (Java Runtime Environment) or JDK and Jython
|-
| Iron Python Actions || .NET CLR or: Mono (on non-Windows systems)
|-
| Ruby Actions || ruby
|-
| Java GUI Automation || JRE (Java Runtime Environment) or: JDK (recommended)
|-
| Windows GUI Automation || .NET CLR
|-
| WebTest (Selenium Webdriver) || JRE (Java Runtime Environment) webDrivers matching your web-browser version
|-
| Mobile Test (Appium) || JRE (Java Runtime Environment)
|-
| Bridged C Actions || C compiler toolchain (GCC, Clang, VisualC, Mingw or Borland)
|-
| Octave (Matlab scripts) || GNU Octave or a real Matlab
|-
| OCR (VNC, Screen Automation) || Tesseract language specific tessdata files
|-
| Vector/Canoe Plugin || .NET CLR
|-
| OPC Library || Python3 + opcua package
|}

== <div id="Java_Installation">Java Installation</div> (for Groovy Actions, Web- and Mobile Testing) ==
You can either install a plain Java Runtime Environment (JRE) or a full Java Development Kit (JDK). If only a JRE is installed, some functions will not work,
and we therefore recommend a JDK - typically at its standard location, "<CODE>C:\Program Files\Java\jdk-xxx</CODE>" (Windows), so it will run out of the box.
 Expecco will try to figure out if and where Java was installed, but it it also possible to specify explicit paths via the settings dialog.

Notice, that due to changed regulations by Oracle (i.e. legal restrictions), we may no longer provide a Java installation bundled with expecco;
you should navigate to the Oracle (or OpenJDK) website and install it from there.

Also notice, that on most systems, a Java is already installed, but it may be a runtime environment only.
Please verify, that a JDK is installed for the full set of features.

The expecco installation does include some required jar files (eg. "groovy.jar", selenium jars and drivers etc.), but you may want to verify that they are the most up-to-date versions.

==== Selenium WebDriver ====
Especially the Selenium drivers (which are used to remote-control a Webbrowser when testing or automating graphical user interfaces in a browser) depend on the concrete browser version (i.e. Chrome version, Firefox version, etc.). Older drivers do not always work with a newer browser.

The deployed installation package includes a number of drivers for versions which were in use at that time, but especially due to automatic updates, these may be outdated on your machine. Please follow the instructions given by expecco and/or read [[Selenium_WebDriver_Plugin/en#Update_WebDriver|"Update WebDriver"]] when it encounters a problem.
 The GUIBrowser's connect dialog will check for version compatibility and offer an update function if required.

== <div id="DOTNET_Installation">.NET Installation</div> (for the .NET bridge, Windows Apps, IronPython Actions and some Plugins 1) ==

On Windows, a .NET framework is usually already installed.
 On Unix/Linux systems, you can install "Mono", which may provide enough functionality for your needs.
 Be aware, that some functions - especially GUI functions - may not be present or may not work perfectly (if at all) under Mono.

Mono can be downloaded from [https://www.mono-project.com/download/stable/ the Mono project web site].

1) for example, the Vector/Canoe plugin requires .NET (among others).

== <div id="Node_Installation">Node Installation</div> (for Node.js Actions) ==

Goto [ https://nodejs.org/en ] or [ https://nodejs.org/de/download/ ] and select the appropriate package for your machine.
When asked if additional packages are to be downloaded, answer "yes".
(Under Windows, VisualStudio build tools will then also be installed, in case any node module needs to be compiled from C/C++ code).

Open the node interpreter settings ("''Extras''" → "''Settings''" → "''Execution''" → "''External Script Interpreters''" → "''Node''") and verify that the "<code>node</code>" command is found along your <code>PATH</code> variable settings by clicking on the "?"-button. If found, its version should be shown.

If not found, either restart expecco (if you installed node while expecco was active), or enter the path to your node interpreter into the path field. You may even have to restart your cmd/shell session, in case the old shell environment does not contain the path to the new installed node.

== <div id="Python_Installation">Python Installation</div> (for Python Actions) ==

Expecco is delivered with an installation package for a relatively new Python version (currently Python 3.11.6 (expecco 23.2)), but of course, new versions are constantly released and the included Python might be outdated. You can (and probably should) download other versions [ https://www.python.org/downloads/ ].
Notice, that there are both packages for python3.x and python2.7 available, and you may have to install both, depending on the Python code to be executed later (although python2 is more and more becoming obsolete, there may still be frameworks for that old version to be found and used).

You can start by installing a Python3.x version only.
By the time of writing this document, the most recent Python version is 3.12, but expecco is known to work with older versions.
Be aware, that there are syntactic differences between Python2.x and Python3.x; for example "<code>print ...</code>" is a statement in 2.x whereas "<code>print(...)</code>" is a function call in 3.x.

Open the Python interpreter settings ("''Extras''" → "''Settings''" → "''Execution''" → "''External Script Interpreters''" → "''Python''") and verify that the "<code>python</code>" command is found along your <code>PATH</code> variable settings (click on "?").

[[Bild:PythonSettings.png|700px|PythonSettings]]

=== Python Commands ===

Notice, that there are 3 command fields, which can be set:
* Python Cmd Path
:is used if no explicit version is specified in a python action
* Python3 Cmd Path
:is used if the python action explicitly asks for python3
* Python2 Cmd Path
:is used if the python action explicitly asks for python2

Be aware and reminded, that these are different python interpreter instances: you cannot run both Python2 and Python3 code within the same python interpreter instance.

If not found, either restart expecco (if you installed Python while expecco was active), or enter the full path to your Python interpreter into the path field.

Make sure that the correct Python version is displayed (2.x vs. 3.x) when you click on the "?" button.

==== Default cmd paths ====

If no command is specified for one of the Python versions, expecco determines a default path, which is displayed in gray in the corresponding cmd path field.

The following sequence is used until a cmd is found:

*Python-Cmd is empty:
: ''Python3-Cmd-Path'' → ''Python2-Cmd-Path'' → ''Windows registry entry for Python3'' → ''Windows registry entry for Python2'' → "''python''"

* Python3-Cmd is empty:
: ''Python-Cmd-Path'' → ''Windows registry entry for Python3'' → "''python3''"

* Python2-Cmd is empty:
: ''Python cmd path'' → ''Windows registry entry for Python2'' → "''python2''"

You can display the effective Python version by clicking on the "?"-button.

=== Debugging python code ===

==== Debugging in expecco ====
To make your life easier, install a Python debugger; either:
pip install debugpy
or
pip install ptvsd
(they are more or less interchangeable, but "<code>ptvsd</code>" is outdated (no longer maintained) and replaced by the newer "<code>debugpy</code>")

Without a Python debugger, breakpoints cannot be placed in bridged Python code,
and you will not get a debugger on Python exceptions
(you should then see a warning and hint to install "debugpy" on the Transcript and in the info area).

To ensure that the breakpoints are observed, please uncheck the "Disable debugger" checkbox.

=====Problems with debugging=====

======Debugger does not start======

If the path for Python is specified with the variables "''%ProgramFiles%''" or "''%ProgramFiles(x86)%''", debugpy does not start.

Python: failed to enable PythonDebugger on port ..: [WinError 2] the system cannot find the file specified.

The remedy is to use the specific path such as "''C:\Program Files''" or "''C:\Program Files (x86)''".

======Warnings in output======

Debugger warning: It seems that frozen modules are being used, which may
make the debugger miss breakpoints. Please pass -Xfrozen_modules=off
to python to disable frozen modules.
Note: Debugging will proceed. Set PYDEVD_DISABLE_FILE_VALIDATION=1 to disable this validation.

In Python 3.11, the core modules essential for Python startup are “frozen”. ...
This reduces the steps in module execution process. Interpreter startup is now 10-15% faster
in Python 3.11. This has a big impact for short-running programs using Python.

It's not possible for the debugger to debug frozen modules as the filename is definitely required to hit breakpoints.

To deactivate the warning, set the environment variable PYDEVD_DISABLE_FILE_VALIDATION to 1, as described in the warning. Notice that the bridge needs to be restarted for the environment variable change to be effective (and possibly even expecco, unless you have specified that variable in "''Extras''" → "''Settings''" → "''External Script Interpreters''" → "''Environment Variables''")

==== Debugging in an external IDE ====
For more in depth debugging, you can run the Python bridge in an external IDE (like PyCharm) and use the debug features of the IDE.

For this, you should save the Python bridge code to a file or copy it to the clipboard using the "''Copy / Save Bridge Code...''" button.
Then open this python file in the IDE, and start in debug mode.

The Expecco Python blocks are called in the line:
result = actionFn(actionArgs, actionOutPins)

You can then step into the block code with a breakpoint at these lines.

In order for Expecco to connect to this Python bridge (instead of starting a new one),
you must first tick the checkbox "''Connect to already running bridge''" and terminate any previously running Python bridges (via "''Extras''" → "''Debugging''" → "''Shutdown all Bridge Connections''").

=== pip2 vs. pip3 vs. pip ===
To install Python packages, use the "<Code>pip</Code>" command. However, this command is usually a symbolic link to either "<Code>pip2</Code>" or "<Code>pip3</Code>".

You should use "<Code>pip3</Code>" to install packages for python3, and "<Code>pip2</Code>" for python2. Thus, it is safer to use one of those or "<Code>python3 -m pip install ...</Code>" instead of "<Code>pip install ...</Code>" to ensure that the module is installed for the current version.

On some systems, no pip2 command is present by default (and installing python3 will define the "<Code>pip</Code>" command as an alias to "<Code>pip3</Code>".

To get "pip2" on those systems, execute (on the command line):
wget https://bootstrap.pypa.io/get-pip.py
python2.7 get-pip.py

Things become even more confusing, if you have multiple python versions installed (for example, python3.7 and python3.9). Then, it is best invoke pip via the python command itself, eg. with: "<code>python3.7 -m pip install ...</code>".

=== Getting pip ===
Some Python installers seem to not install pip (at least it happened to us once, that "pip" was not found after a python installation).
 If "python -m pip" gives a warning, do the following:
* download "https://bootstrap.pypa.io/get-pip.py" (use "''Save As''" in a web browser, and save it to the desktop)
* open a cmd/shell window in that folder.
* execute "python get-pip.py"

== Jython Installation ==
Jython is a Python interpreter which runs inside a Java virtual machine, and thus has direct access to Java classes and objects. 
As a prerequisite, Java needs to be installed on your machine. Then goto [ https://www.jython.org/download.html ], download the Jython installer and run it (choose "standard install" or "full install").
 Remember the target directory. The jython command will be found there.
 If the "jython" command is not in your PATH, enter its full path in the "''Extras''" → "''Settings''" → "''Execution''" → "''External Script Interpreters''" → "''Jython''" settings dialog.
 However, it is usually better to add the path to your PATH variable (eg. as setup in the Windows environment settings, autoexec.bat or Unix's login.rc), and just give "jython".
 Notice that previous Jython versions were 2.x Pythons, which will sooner or later become outdated. It is recommended to download or upgrade to a 3.x version (if your code is 3.x compatible).

== Iron Python Installation ==
IronPython is a Python interpreter which runs inside the Common Language Runtime system, and thus has direct access to C# classes (and of yourse all other objects which live inside the CLR world). 
As a prerequisite, you'll need a .NET CLR (common language runtime) or mono (on Unix systems). On Windows systems, a reasonable CLR Version is usually already installed.
 Then go to [ https://ironpython.net/download ] or [ https://github.com/IronLanguages/ironpython3 ] and follow the instructions.

After the download, IronPython is typically installed in "<Code>C:\Program Files\IronPython 3.x</Code>", and you should enter the path "<Code>C:\Program Files\IronPython x.y\ipy.exe</Code>" into the IronPython command path field in the python settings dialog (or simply "ipy", if it is in your PATH).
Notice that previous IronPython versions were 2.x Pythons, which became obsolete. It is therefore recommended to download or upgrade to a 3.x version (if your code is 3.x compatible).

== Ruby Installation ==
Goto [ https://rubyinstaller.org/downloads ] and install ruby.
Then make sure that ruby is in your <code>PATH</code> setting or set the path to the command in the "''Extras''" → "''Settings''" → "''Execution''" → "''External Language Interpreters''" → "''Ruby''" settings. Typically it will look like "<code>C:\Ruby32-x64\bin\ruby.exe</code>" on windows.
 Create a new Ruby action and execute it to see if it works.

== Julia Installation ==
Goto [ https://julialang.org/downloads] and install.
Then make sure that julia is in your <code>PATH</code> setting or set the path to the command in the "''Extras''" → "''Settings''" → "''Execution''" → "''External Language Interpreters''" → "''Other''" settings. Typically it will look like "<code>%LOCALAPPDATA%\Programs\Julia-1.10.4\bin\julia.exe</code>" on windows.
 Create a new Julia action and execute it to see if it works.

== C Compiler Toolchain Installation (for C-Actions) ==

For a quick verify if the setup is working, create a new (default) bridged C action and execute it (it should generate a "Hello World" message).

==== C Compiler Toolchain Installation ====

You need a C-compiler toolchain to be installed for C-coded actions.
* On Unix/Linux systems, these are usually already present on the machine (try "<Code>cc --version</Code>" in a shell window; if you get a reasonable response, you are usually ready to go).
* On Windows, install one of "Borland", "VisualC", "VisualC Redistributable" or "MingGW". We recommend MingGW.
* On OSX, you have to install "XCode" or the "Command Line Tools" subset.

===== Windows + Borland (32bit) =====
* get the free Borland command line tools (see https://borland-c.software.informer.com/5.5) and install them (typically, under "<code>C:\borland\bcc55</code>")
* ensure that the <code>link.cfg</code> and <code>bcc55.cfg</code> files are present in the "<code>C:\borland\bcc55\bin</code>" directory.
* verify the installation by typing "<code>bcc32</code>". A help message should appear.
* in the expecco settings, goto "''Execution''" → "''External Script Interpreters''" → "''CBridge''" and select the appropriate CC-Script ("<code>compile_windows_bcc.bat</code>"), which tells the bridge how to compile the C-action code (more below).

===== Windows + Visual-C (32 or 64bit) =====
* similar to above, check for the "<code>cl</code>" command.
* in the expecco settings, goto "''Execution''" → "''External Script Interpreters''" → "''CBridge''" and select the appropriate CC-Script ("<code>compile_windows_vc32.bat</code>", "<code>compile_windows_vc64.bat</code>" or "<code>compile_windows_vc64_redist.bat</code>"); see below.

===== Windows + Mingw (32 or 64bit) =====
* get the mingw64 compiler and install it (best is under "<code>c:\mingw64</code>" or "<code>c:\program files\mingw64</code>").
* verify the installation by typing "gcc --help".
* in the expecco settings, goto "''Execution''" → "''External Script Interpreters''" → "''CBridge''" and select the appropriate CC-Script ("<code>compile_windows_mingw32.bat</code>" or "<code>compile_windows_mingw64.bat</code>"); see below.

When a C-coded action is about to be executed, its C-code will be compiled ''just in time'' using that toolchain. For that, the cBridge executes a configurable batch or shell script. For some commonly used toolchains, corresponding scripts are provided, but you can or may have to add your own script(s), in case you need special compile options, additional link library options or if you want to compile with a compiler not supported by the standard installation (eg. Intel compilers).

If you get compilation errors, take a look at the "compile_xxx" scripts in "<code>packages/exept/expecco/bridgeFramework/cBridge/cLibrary</code>" under the expecco installation folder.

If required, add your own script to call whatever compiler you need, and select it in the cBridge settings dialog
("''Extras''" → "''Settings''" → "''Execution''" → "''External Language Interpreters''" → "''CBridge''"). You must also add your own script, if special compiler flags or additional standard paths are to be setup.

Notice, that we currently do not provide compilation scripts for C++; however, by declaring entry-functions (as <code>extern "C"</code>) in your C++ code, these can be called from C.

If no toolchain is installed, you can still see and edit C-code actions, but obviously not execute them.

===== Windows + Mingw32 =====
Same as above; recommended installation directories are "<code>c:\mingw32</code>" or "<code>c:\program files\mingw32</code>"

==== C Compiler Toolchain at Test-Execution Time ====
You can tell expecco to embed a pre-compiled object file into the saved "<code>.ets</code>" suite file ("''Store Object Files in Project''" checkbox in the CBridge settings dialog). If checked, C-Bridge actions will be compiled by your current session (using the configured toolchain) and the generated object file(s) will be saved with the suite. When the suite is later executed, no compiler toolchain will be needed on the test machine. Make sure that all required C actions are executed at least once.

Expecco does not include cross compilation support; that means, that only object files for the current architecture can be generated. However, if you load the suite into another architecture's expecco, additional object files for that other architecture will be generated and added to the ".ets" when saved. So afterwards, object files for both architectures will be present in the ets.

To summarize, if you want to deploy a library with embedded C-actions, which will have to be executed on (say) both a Linux and a Windows machine, where both test-execution machines have no compiler toolchain installed, perform the following steps:
# load the suite on a Linux machine (with C-compiler toolchain available)
# ensure that the "''Store Object Files''" flag is checked.
# Save the suite
# load the saved ".ets" on a Windows machine (with C-toolchain available)
# Save it again.
The last saved ".ets" will now contain object files for both architectures.
Be aware, that you may have to repeat the steps for 32 and 64 bit architectures, if the suite is to be executed eventually on both.

Be reminded that this procedure is not needed, if the machine which executes the tests does have a C-toolchain installed. And especially, if it is the same as your development machine.

== <div id="Cling_Installation">Cling Installation</div> (for RootCling Actions) ==

Support for Cling is "''work in progress''" and currently considered an "''experimental''" feature which is not available/enabled in the current deployed version.

Cling (aka "Root Cling") is a dynamic language system for C/C++.
Code can be entered in C++, which is dynamically (just in time) compiled to fast machine code.

Cling can be downloaded from the [https://root.cern/cling Cern web site] and/or installed via a package installer:

;Linux:
: -- see https://root.cern/download/cling/ --
Download one of the tar archives and unpack the files into some folder (such as "/opt/cling").

;Windows
: Sorry, to our knowledge, there exists no ready-to-install version for Windows at the time of writing this document.

;OS X(Mac):
: <code>brew install cling</code>

Depending on whether cling is found along your path, or you want to select a particular version,
specify the cling installation folder in the cling settings dialog "''Extras''" → "''Settings''" → "''Execution''" → "''External Language Interpreters''" → "''Cling''".
 There, click on the "?" button to verify that cling is found.

== Smalltalk Installation ==

Support for bridged Smalltalk is "''work in progress''", currently disabled and is planned for a future version.
However, scripted Smalltalk is already available.

== Scheme Installation ==

Support for bridged Scheme is "''work in progress''", currently disabled and is planned for a future version.
However, scripted Scheme is already available.

You can configure expecco to either use any standard scheme interpreter (whichever is installed as "scheme" command),
or to use an explicit implementation. Currently, supported are ChezScheme, ChickenScheme and Racket/MZScheme.

=== Chicken Scheme ===

[https://code.call-cc.org Chicken] can be compiled from [https://code.call-cc.org source] or installed via a package manager.

;Windows:
: https://chocolatey.org/packages/chicken/
: or:
: see https://wiki.call-cc.org/platforms#microsoft-windows-

;Linux:
: see https://wiki.call-cc.org/platforms#linux

;OS X (mac):
: brew install chicken
: or:
: see https://wiki.call-cc.org/platforms#mac-os-x

=== Chez Scheme ===

See [ https://github.com/cisco/ChezScheme ] for instructions.

A Windows binary and sources of release 9.5.4 are found at [ https://github.com/cisco/ChezScheme/releases/tag/v9.5.4 ].

== <div id="GnuPlot_Installation">GnuPlot Installation</div> (for Graph Attachments to the Report) ==

Gnuplot makes it easy to add graphs for measurement data or statistics to the
report and/or to create attachments for them.
To install gnuplot execute (in a terminal):

;Linux:
: -- to be determined and documented --
: please refer to the official Gnuplot website: http://www.gnuplot.info/download.html

;Windows:
: -- to be determined and documented --
: please refer to the official Gnuplot website: http://www.gnuplot.info/download.html

;OS X (Mac):
: <code>brew install gnuplot</code>
: or download a binary package eg. from:
:  https://csml-wiki.northwestern.edu/index.php/Binary_versions_of_Gnuplot_for_OS_X

== <div id="GNU_Octave_Installation">GNU Octave Installation</div> (Matlab compatible Scripting) ==

;OS X (Mac):
: Download a dmg from
:  https://wiki.octave.org/Octave_for_macOS
: or:
:  https://octave-app.org
: or:
: <code>sudo port install octave</code>

;Windows:
:Download from https://www.gnu.org/software/octave/download.

Warning: octave is huge (roughly 1Gb download).
 Also notice: octave needs gnuplot to generate image files from graphs.

If you are already using Matlab, set the path to the matlab executable in the "''Execution''" → [[Settings ExternalToolsSettings/en#GnuOctave_Path | "''External Script Interpreter''"]] settings.

==Dart Installation==
Goto [https://dart.dev/get-dart dart.dev] and follow the instructions there.

==R Installation==
Goto [https://www.r-project.org/ www.r-project.org] and follow the instructions there.
 OpenSuse users can "<code>zypper install R-base R-base-devel</code>".

== Go ==
For downloads, go to [https://go.dev/dl/ https://go.dev/dl/].
 OpenSuse users can "<code>zypper install go-devel</code>".

Make sure that go is in your PATH or else define the full pathname to go in the "''Execution''" → "''External Script Interpreters'' "→ "''Others''" settings dialog.

== TCL, and all the others ==
If you use those, you probably know how to install and update them.
Follow the usual installation instructions and - unless the interpreter is found along your PATH setting, define the path in the expecco "''Execution''" → "''External Script Interpreters'' "→ "''Others''" settings dialog.

== <div id="OCR">OCR</div> (Optical Character Recognition) ==
In order to extract text from bitmap images,
an OCR framework is needed. It is also needed if you want to automate the local screen or a VNC screen AND you need to extract text or numeric values from it.

Both open source and commercial frameworks can be found and used.
Good results are achieved by the free (and open source) "Tesseract" framework,
which we recommended, unless you already have a more powerful non-free commercial OCR framework at hand
(although supported, we do NOT recommend capture2Text or GNU-ocrad; they do not provide detailed per-word information and/or delivered poor recognition results. At least at the time this document was written).

Tesseract is hosted at [ https://github.com/tesseract-ocr/tessdoc ] and can be downloaded from [ https://github.com/tesseract-ocr/tessdoc/blob/master/Downloads.md ].
 Follow the installation instructions there.

;Windows and OS X
:binaries are found at [ https://github.com/UB-Mannheim/tesseract/wiki ]

In order to recognize national language characters (eg. accents, diareses/Umlauts), you'll also need language specific Tesseract-Data files. Please also install those for German, French, etc. from [ https://github.com/tesseract-ocr/tessdata ].

== AI (Tensorflow) ==
These are typically used via Python actions, and installed using a Python package manager (pip). Please refer to Tensorflow web pages for details.

Tools ClassBrowser/en

2026-02-23T11:06:09Z

Sv: Änderung übernommen aus altem Wiki von cg, 25.11.25

== Overview ==
The Class Browser provides full access to the underlying class library and development framework. Both existing code can be browsed (to find and understand code API functions), changed and and new classes can be added with this tool while expecco is running (i.e. "while-running-surgery" or "hot code swap").

The tool's [http://live.exept.de/doc/online/english/tools/newbrowser/TOP.html documentation] is part of the official [http://live.exept.de/doc/online/english/TOP.html Smalltalk/X Online Documentation].

This is an expert tool, useful to coders only.

Notice, that you should have checked the "''Install Source Code''" toggle in the initial installation; otherwise, the browser will only be able to show the class's protocol, but not the actual source code. If you did not, please repeat the installation process, checking ONLY the "''Install Source Code''" toggle.

Warning: the underlying expecco framework classes are in part open to be viewed and even modified by the Class Browser. This allows for features to be added or fixes to be made even by our customers. We offer this changeability feature as a last-level-safety feature: in a high emergency situation, it may be required to add a fix to ensure ongoing production, even if that contrasts with general engineering practices. On the other side, it opens the door to possible bugs being introduced: you should be very very careful when doing any change to any framework class, and in general, we do NOT recommend it.

== Most Interesting Classes ==

You should use the browser to find additional useful operations, for which no elementary blocks are found in the expecco standard library. Be aware, that there are more than 50000 more-or-less useful functions to be found and used in elementary action blocks, so take your time to investigate the system and don't get overwhelmed by the sheer number of functions.

A few tricks help to find things quickly:

* install the sources (without, no comments and of course, no source code is shown). The source code is very well documented, and without it, things are much harder to find. By default, the install dialog has this option enabled; unless you explicitly uncheck to toggle in the installation dialog, the sources should be available.

* all classes are classified into groups. For example, all collection classes will be found under the "''Collections-*''" category, numbers under "''Magitude-Numbers''", etc. The top-left pane of the browser shows the categories. Look there first.

* if you know the name of the class (or part of it), use the "''Find Class...''" menu function in the category list. Use wildcards, if you only know part of the name (or guessed it). For example, "*Array*", "*Stream*" or "*File*".

* if you know the name of the operation, similar search options exist. Use the "''Find Implementors...''" function in the top-right pane. For example, to find all operations which have something to do with hexadecimal encodings, try implementors of "*hex*".

* many classes provide in-code documentation. Switch to the class side (toggle the "''Class/Instance''" button and look for methods named "''documentation''" and "''examples''".

* you can find calls to a function via the "''Senders of...''" menu function in the top-right pane. This shows you where and especially how a particular function is used by others in the system. As a example, look for senders of "''readFrom:*''" to find string-to-number converters.

=== Classes You Should Know About ===

* [https://live.exept.de/doc/online/english/overview/basicClasses/misc.html Date, Time, Timestamp and TimeDuration]

* [https://live.exept.de/doc/online/english/overview/basicClasses/collections.html Collection (abstract), SequenceableCollection (abstract), Array, ByteArray, CharacterArray, String, Set and Dictionary]. Especially the String class is worth knowing; and remember that it inherits a lot of functionality from its superclasses (CharacterArray, ArrayedCollection, SequentialCollection and Collection).

* [https://live.exept.de/doc/online/english/overview/basicClasses/streams.html ReadStream, WriteStream, ExternalStream, PipeStream, Socket]. All those inherit from Stream, which you should also take a look at.

* Files & Directories: look at Filename and subclasses

* [https://live.exept.de/doc/online/english/overview/basicClasses/numeric.html Number, Float, Integer, Fraction, FixedPoint]

* [https://live.exept.de/doc/online/english/overview/basicClasses/misc.html OperatingSystem: UnixOperatingSystem/WindowsOperatingSystem, -Registry, SocketAddress, OSProcess]

== Interactive (Hot Code Swap) ==

Notice that any change made to the system will be immediately effective. It is even possible to change code in the browser while the code is executing (however, the currently running function will complete its execution and new code will be called with the next invokation)

== See Also ==

[http://live.exept.de/doc/online/english/TOP.html Smalltalk/X Online Documentation]
 [http://live.exept.de/doc/online/english/programming/syntaxCheatSheet.html Smalltalk/X Syntax Cheat Sheet]
 [http://live.exept.de/ClassDoc Smalltalk/X Class Documentation / Online Reference Manual]

Back to [[Online_Documentation#Tools | Online Documentation]].

[[Category: Tools ]]

Glossary/en

2026-02-23T11:04:12Z

Sv: Änderung übernommen aus altem Wiki von cg, 25.11.25

== Action, Step and Activity ==
In expecco, an "''Action Block''" (or "''Action''" or "''Block''" for short) refers to the definition of how an action is done. It is therefore also called occasionally "''Action Definition''". In the application, action definitions are found in a tree like organization at the left of the window.
Actions can be specified in multiple ways:
* as an activity diagram, with interconnected steps
* as a list of sequentially executed steps (either as keyword list action or in a test plan)
* as a piece of code in a programming language
* as a remote procedure call (service call)

Actions with an activity diagram are called "''Compound Actions''", and their elements are called "''Steps''".

Actions with a sequence list are called "''Keyword Actions''". Test plans are also a kind of sequence list, but provide additional control for execution (looping, skipping, selecting etc.). Although their elements are also technically steps, they are typically named "Test Steps", "Test Cases" or "Test Plan Items".
 All other actions are called "'Elementary Actions''".

A step is an action being placed (instantiated) in either an activity diagram or a sequence list.
Notice that the same action can be placed into multiple other compound actions, keyword actions or test plans. Thus, an action definition can be resused (possibly with different parameters) in multiple places.

When a step receives its required input values, it starts executing. For this, a so called "''Activity''" is created, which executes the step's action. Conceptionally, a thread (lightweight process) is created, which executes the step's action with the given parameters (1). Also notice, that multiple activities can be active in parallel, even executing the same step at the same time.

Notice that in the literature, the meaning of "Action", "Step" and "Activity" is often unclear, and the exact definition is often unclear.

See also: [[Tree Elements/en#Action_Blocks|Action Block]] in the [[Tree Elements|''Tree Elements'']] documentation.

1) technically a thread pool is used, and a free one is chosen to execute it.

== Activity Log ==
Whenever expecco executes some action (block), all of its input and output values are recorded in an activity log.
In addition, explicit and implicit log-messages may be generated (implicit by the execution engine, explicit by calls to "logInfo", "logWarning" etc. or action steps). In addition, the start- and execution times are recorded.

== AIDYMO==
Central management system for Automation. Was previously known as expeccoALM.

== Black Box Test ==
In a [https://en.wikipedia.org/wiki/Black-box_testing "''Black Box Test''"], the test-machine and test-application are completely separated from the System Under Test (SUT). No knowledge about the internals (data structures, object model etc.) of the SUT is known when testing. The test only operates against official external interfaces, such as input/output, data and configuration files, command line interfaces, GUI interfaces or communication protocols.

The opposite being a [[#White Box Test|"White Box Test"]], which executes inside the SUT and has full access to all internal details (i.e. functions, data objects etc.).

Expecco supports both, "Black Box" by various libraries which provide interfaces to commonly used external interfaces, and "White Box" via code injection mechanisms, such as "Groovy" or "VisualBasic".

Mixed mode testing is called [https://en.wikipedia.org/wiki/Gray_box_testing "Grey Box Testing" (wikipedia)].
 See also: [[#White Box Test|White Box Test]], [[#Gray Box Test|Gray Box Test]]

== Bridged Actions ==

Expecco uses "''bridges''" to implement action blocks written in different programming languages.
A bridge has two sides, one inside expecco, another inside the external scripting language interpreter, which typically communicate via a socket interprocess communication mechanism.
Whenever a bridged action block is to be executed, expecco packs the arguments and additional call information into a message and sends it over to the other bridge side. There, the function's code is executed and a result returned as message back to expecco.

The bridge remains alive, as long as expecco is alive, or the bridge connection is closed explicitly (by the testsuite or via a menu function).

All bridges support code injection, which means that action blocks can be edited inside expecco and are forwarded and installed automatically, when first called. This makes the handling of bridged actions almost transparent and identical to the way in which internal actions (Smalltalk and JavaScript) are handled. For some languages, expecco even includes a debugger with breakpoint-, single step and data inspection features.
Currently, bridges are provided for Java/Groovy, Node.js, DotNET/CLR, Python, remote Smalltalk and C/C++.

== [[CompoundBlock Element|Compound Action Block]] ==
An action block which is defined by an activity diagram. Its execution semantics are defined by a network of interconnected steps. These themselves can be compound- or elementary steps.
 See [[CompoundBlock Element/en|Compound Block]] in the [[Tree Elements|''Tree Elements'']] documentation.

== [[DiagramElements-Step|Compound Step]] ==
A step inside an activity diagram, whose action definition is a compound action block. When triggered, such a step will execute another activity diagram.
 See [[CompoundBlock Element/en|Compound Block]] in the [[Tree Elements|''Tree Elements'']] documentation.

== ".csf" File ==
"''Connection Settings Files''" are used by the [[Mobile Testing Plugin/en|Mobile Testing]] and [[Selenium WebDriver Plugin/en|Selenium WebDriver]] interfaces. The file is a text file contain lines with key-value pairs in the format:
key: value
each pair specifies an attribute or required capability of the connection.
Typically, these are generated via the [[Expecco GUI Tests Extension Reference/en|GUI browser's]] "''Connection''" dialog and kept as attachments inside the suite.

== ".csv" File ==
"''Comma Separated Values Files''" are files as generated by Excel and other Spreadsheet programs, by databases and many other record-oriented programs for data interchange. These files represent data records as textual (i.e. human readable) text lines, where the columns (fields) are usually separated by commas (although often semicolon is used as field separator). The very first line of a "csv" file contains the column names.
Expecco can read and write "csv" files, eg. for parameter sets or via action blocks. It is also possible to give a CSV file to the command line, to preset top-level environment variables from it.

== Dead Key ==
Prefix key used to enter diacritic characters (eg. Umlaut and accents). If enabled, the keyboard characters <">, <'>, <^> and <`> will be ''dead'' until a followup character is typed. Then a new character is composed (eg. <ä> from <"> and <a>).
If followed by a space or the dead key, the dead key is entered. If the combination is invalid, two characters will be entered. Thus, to enter the dead key character alone, press a space as second character (or press the dead key twice).
Because dead key processing can be inconvenient when entering program source code, they are disabled by default. This default can be changed in the settings dialog under "''Look and Feel''" - "''Keyboard Settings''". In addition, edit text windows provide a popup menu entry to enable/disable deadkey processing as a per editor. See also [https://en.wikipedia.org/wiki/Dead_key wikipedia].

== DLL (Dynamic Link Library) ==
Are dynamically loadable programs or libraries. In the Unix world, these are typically called "shared objects".
Expecco can call into such libraries using elementary DLL-call blocks. These should be used to call driver or utility functions inside a dll, especially if you do not have access to the function's source code or header definition files.
 
See more in [[ElementaryBlock_Element/en#DLL-Calls | Elementary Blocks - DLL Calls]].

== DUT (Device Under Test) ==
See [[#SUT_.28System_Under_Test.29 | System Under Test]] in this document.

== [[ElementaryBlock Element|Elementary Block]] ==
An non-compound action block. I.e. any action which is not defined by an activity diagram or keyword list, but either builtin (well known to expecco), a call to an external function or application, or defined programmatically as a piece of textual program code in one of the supported programming languages.
 See [[ElementaryBlock Element/en|Elementary Block]] in the [[Tree Elements|''Tree Elements'']] documentation.

== [[DiagramElements-Step|Elementary Step]] ==
A step inside an activity diagram, whose action definition is an elementary block. When triggered, such a step will execute either a builtin function, an existing function inside a DLL, another program or a piece of code written in one of the programming languages supported by expecco.
 See [[ElementaryBlock Element/en|Elementary Block]] in the [[Tree Elements|''Tree Elements'']] documentation.

== Environment ==
Variables are bundled together in so called ''Environments'', which are technically collections of key-value pairs (Dictionary/HashTable). Environments can be attached to individual compound actions, to individual testcases, to a testplan and are also attached to the suite. There are also temporary environments attached to the current execution, the current browser window and the current expecco session.

During execution, environments are linked to form a parent-child hierarchy, and variables are fetched along this hierarchy. Thus, variables declared at the block level may shadow variables at the testplan-level, which may shadow variables declared in the current testsuite.
 Typically, the top-level suite's environment (so called "''ProjectEnvironment''") is used most of the time.

It should be noted, that command line shell variables are also held in a so called "environment". In this Wiki, this will be named "shell environment" to avoid confusion. However, it should be noted, that the expecco top-level environment will allow for the shell environment to be referenced (as "$(xxx)").

== Environment Freeze Value ==
A variable attached to an action step's input pin. Instead of being provided via a connection from another output pin, this provides a value from an environment variable.

== ".elf" File ==

"<code>elf</code>" stands for "''Expecco Log File''" and is the native format in which result files are written. "<code>elf</code>" files contain all of the execution, trace and data-flow information and the original suite as executed. "<code>elf</code>"-files can be reloaded at any time into the expecco UI, values of that run be inspected and it is even possible to reexecute the original test. Also, any of the other reports can be regenerated, possibly with different report options (i.e. detail). Technically, "<code>elf</code>" files are zip-containers containing traces, logs and the original test suite in XML-format, and any attachments (screen shots, measurement data etc.) in whatever format they were written (images usually as PNG). They can be read and processed by third party tools (i.e. unzipped, and then processed with an XSL/XSLT ruleset to generate custom reports or to transport the result to any other XML-capable QM system).

== ".ets" File ==
"<code>ets</code>" stands for [[#TestSuite Element |"''Expecco Test Suite''"]]. These are technically zip-containers, containing the test suite in XML-format and any attachments in whatever format they where imported or generated. In addition, an index (manifest) is present, which allows for fast access to certain information without a need to read the whole zip archive. Also, signatures ensure that the manifest and remaining contents are in sync. Therefore, "<code>.ets</code>" files should not be manipulated manually, as the consistency of the suite may be harmed.

== expecco ==
Does the name "expecco" mean anything?
No, but it is a pun on the latin word "peccare"/"peccō" which means "to make a mistake", "an error" or "to sin". So ex-pecco is our answer to get rid of those.

== FMI (Functional Mockup Interface) ==
see FMU below

== FMU (Functional Mockup Units) ==
Functional Mockup Units are packaged simulation components, typically written in C (but not required to be), which can be loaded into a simulation framework. FMUs implement a standardized interface (FMI V2.0 / FMI V3.0) and are popular in areas of factory automation, automotive and robotics (see fmi-standard.org https://fmi-standard.org). Starting with release 23, Expecco supports loading, executing and interacting with FMU running both on the local or a remote host.

== Freeze Value ==
A fix (static) value attached to an action step's input pin. Instead of being provided via a connection from another output pin, this provides a constant value to an action step's input.
Notice that starting with expecco release 19.2, variable references can be embedded inside a String-Freeze-Value using the "<code>$(xxx)</code>" notation, where "''xxx''" is the name of a variable or input pin of the enclosing compound action. See also [[#Environment Freeze Value | Environment Freeze Value]] in this document.

== FTP (File Transfer Protocol) ==
A [https://datatracker.ietf.org/doc/html/rfc959 standardized protocol] to transfer files between machines.

== Functional ID (FID) ==
A UUID attached to every action block inside expecco. This identifier is assigned once and never changed again. Inside expecco, actions are referred to via their FID or Version ID, independent of their name. Actions with the same FID are considered to be (possibly different versions) of the same action.

== Gray Box Test ==
Some knowledge about internal interfaces of the System Under Test are known. For example, data structures or function entries inside the SUT are exploited and used. The categorization of a test as white- or gray box test is vague - there is often no clear line of separation between them.
 See also [[#Black Box Test|Black Box Test]], [[#White Box Test|White Box Test]], [https://en.wikipedia.org/wiki/Gray_box_testing "Grey Box Testing"] in Wikipedia.

== Groovy ==
A language interpreter which runs on top of a Java Virtual Machine (JVM), with a syntax very similar and almost compatible to Java. Used in expecco to call into Java interfaces or define required callback and listener classes, in case the SUT or the interface to the SUT require those.

Groovy code is compiled to bytecode inside the JVM, which is further Just-in-Time compiled to fast machine code within the target JVM. Thus, it can interface to any Java code (from jar or class files) and it executes at full Java speed.

Expecco allows for Groovy code to be executed both on the local machine (the one on which expecco itself is running) and on remote machines which are reachable via a TCP/IP connection. Multiple of these connections are possible and handled simultaneously in parallel, making it possible to interact with many hosts in a distributed system or when testing both ends of a communication protocol.
 See [[Expecco API/en#Groovy Elementary Blocks|"Groovy Elementary Blocks"]] in the ''Expecco API Document'' and [[ElementaryBlock Element/en|Elementary Block]] in the [[Tree Elements|''Tree Elements'']] documentation.

== Groovy Elementary Block ==
An action block which is defined by an execute function which is written in the Groovy language. The block's code will be executed by a Groovy interpreter on a Java Virtual Machine (JVM). The JVM may run either on the local or on a remote machine. Expecco uses code injection techniques to implant the code into the SUT dynamically at run time. Except for sealed systems, it is normally not required to specially instrument or otherwise recompile the code in the SUT.
 You have to install "java" from the official website (due to legal reasons, we cannot provide a java interpreter with the expecco installer).
 See [[Expecco API/en#Groovy Elementary Blocks|"Groovy Elementary Blocks"]] in the ''Expecco API Document'' and [[ElementaryBlock Element/en|Elementary Block]] in the [[Tree Elements|''Tree Elemens'']] documentation.
== GUI (Graphical User Interface) ==
GUI tests and GUI automation refers to processes which control an/or verify an application which has a graphical user interface, such as a Windows, XWindow, Java, JavaSwing, JavaFX, VNC, QT etc. interface. This also includes mobile devices such as iPhone (IOS) and Android devices.

== GUID (Global Unique Identifier) ==
A synonym for [[#UUID (Universal Unique Identifier) | UUID]].

== Inconclusive State / Test Outcome ==
See [[#Verdict| "Verdict"]] in this document.
== IPC ==
Short for interprocess communication. Typically a socket, pipe or shared memory.

== IronPython Elementary Action Block ==
Bridged IronPython actions are supported by expecco. IronPython is a python interpreter which runs inside a DOTNET CLR (Common Language Runtime) environment, and has therefore full access to any .NET framework/assembly. It can be used if .NET interfaces are needed, both under native Windows and under Mono (linux/unix/osx).
 You have to install "IronPython" from the official website.
 See [[Expecco_API/en#Bridged_Python_Elementary_Blocks|"Bridged Python Elementary Blocks"]] in the Expecco API document.

== JavaScript Elementary Action Block ==
An action block which is defined by an execute function which is written in a JavaScript like language. The block's code will be executed inside expecco itself (as opposed to Node-Action-Blocks, which are executed by an external interpreter).
 See [[Expecco API/en#JavaScript Elementary Blocks|"JavaScript Elementary Blocks"]] in the ''Expecco API Document'' and [[ElementaryBlock Element/en|Elementary Block]] in the [[Tree Elements|''Tree Elements'']] documentation.

== JSON ==
JSON is a common format to exchange structured data, which originated in JavaScript but is now very common and supported by many applications and in almost any programming language. JSON can represent simple (non recursive) objects as textual (i.e. human readable) text, organized as a nested object hierarchy with key-value associations.
Expecco can read and write JSON both via calls from elementary code and by use of actions from the standard library.
 Because JSON is often used in many other apps, expecco also provides the JSON representation in its data inspector, for easy copy-paste.

== ".json" File ==
A file containing JSON encoded data. Often used for configuration data.
 Expecco can read and write "json" files, eg. for parameter sets or via action blocks. It is also possible to give a JSON file to the command line, to preset top-level environment variables from it.

== Jython Elementary Action Block ==
Bridged Jython actions are supported by expecco. Jython is a python interpreter which runs inside a JVM (Java Virtual Machine), and has therefore full access to any Java framework. It can be used as an alternative to Groovy, if Java interfaces are needed.
 You have to install "jython" from the official website.
 See [[Expecco_API/en#Bridged_Python_Elementary_Blocks|"Bridged Python Elementary Blocks"]] in the Expecco API document.

== Node Elementary Action Block ==
Node.js (or "''NodeJS''" or simply "''Node''") is a language interpreter for JavaScript, which is used in cloud computing, Alexa, IOT and other internet applications. Node is rapidly gaining interest and many packages are already available, covering a wide range of protocols, file formats and interfaces. Both bridged and scripted Node.js actions are supported, and expecco includes good support for bridged Node.js action blocks, including breakpoints and debugging with single stepping.
 You have to install "node" and "npm" from the official website: [https://nodejs.org/en/download/ https://nodejs.org/en/download].
 See [[Expecco API/en#Node.js_.28Bridged.29_Elementary_Blocks|"NodeJS Elementary Blocks"]] in the Expecco API document and [[ElementaryBlock Element/en|Elementary Block]] in the [[Tree Elements]] documentation.

== OCR (Optical Character Recognition) ==
Algorithm which (tries to) extract text from a bitmap image. Expecco can use OCR to extract data from screen- and other images,
and also to automate screen interaction if no higher level UI-interface can be used (see GUI Browser).
Both commercial and free OCR frameworks can be used and configured.
Currently a good choice is the free tesseract OCR framework (see [[Installing_additional_Frameworks/en#OCR_.28Optical_Character_Recognition.29 |Installation notes]] and [[Settings_ExternalToolsSettings/en#External_OCR_Tools_Settings | Configuration notes]].

== OPC-UA (Open Platform Communications Unified Architecture) ==
Is an industry standard for communication in factory automation and machine control.
See [https://opcfoundation.org/about/opc-technologies/opc-ua https://opcfoundation.org/about/opc-technologies/opc-ua/].

== Pin - Consuming Pin ==
An input pin of a step, which does consume its input value when the step starts to execute.
Technically, this takes the next input value from the queued values pending in the input-basket.
Consuming pins are used when an input pin gets its value from another step's output pin.

== Pin - Mailbox (or Telegram) Pin ==
An input pin of a step, which is delivered to an activity even when it is already executing. Normal pins take their value from an input basket associated with the input pin, and values which arrive after the start of the activity will be held in the basket (queued) for the next activation.
In contrast, mailbox pins do not enqueue their incoming values, but instead deliver them immediately to the activity - if it is already running. If the activity is not running, mailbox pins behave like regular unbuffered pins, being triggering or not (but typically, they are triggering). Mailbox baskets are typically used to cancel or break out of a loop, eg. in a service providing action block. I.e. they can be used to implement a cancel-pin function, where internal cleanup actions are still needed.

== Pin - Parameter Pin ==
An input pin of a step, which does not consume its input value and which does not trigger the step.
Used for constants and parameters, especially if the step is to be used in a loop.

== Pin - Triggering Pin ==
An input pin of a step, which triggers the execution of a step.
A step will only start to execute, when all of its triggering pins have received a value.

== Python Elementary Action Block ==
Both bridged and scripted Python actions are supported by expecco, and also both Python2.x and Python3.x can be used inside the same suite (in addition to Jython and IronPython).
 You have to install "python" and "pip" from the official website: [https://www.python.org/downloads https://www.python.org/downloads]. (see also [[Installing_additional_Frameworks/en#Python_Installation|Installing Additional Frameworks]])
 See [[Expecco_API/en#Bridged_Python_Elementary_Blocks|"Bridged Python Elementary Blocks"]] in the Expecco API document.

== R Script Action Block ==
R is a programming language which emphasizes on statistics, math and graph plotting.
 You have to install "r" from the official website (see [[Installing_additional_Frameworks/en#R_Installation|Installing Additional Frameworks]]).

== RPC (Remote Procedure Call) ==
A mechanism by which expecco calls into an external program, such as a Python, NodeJS or C program.
When a remote procedure call is performed, the name of the operation plus any arguments are packed into a message, transferred to the partner, executed there and finally any results packed again into an answer and transferred back to expecco. Thus there is some overhead and the execution is slower than if directly performed by expecco. Typically a no-operation round trip executes in the order of micro- or even milliseconds, whereas internal operations execute in the order of nano- or microseconds. I.e. roughly 1000 times faster. However, if the actual processing takes long compared to the transmission overhead, or if the partner has exclusive access to some device or software framework, a remote procedure call might be the only mechanism, by which a task can be accomplished.

== REST (Representational State Transfer) ==
REST is a remote procedure call mechanism based on JSON encoded packages which are typically (but not required to be) transmitted via HTTP. REST was created (probably) out of frustration of SOAP's complexity.

== Ruby Elementary Action Block ==
Both bridged and scripted Ruby actions are supported by expecco.
 You have to install "ruby" from the official website [https://rubyinstaller.org/downloads https://rubyinstaller.org/downloads].
 See [[Expecco_API/en#Bridged_Ruby_Elementary_Blocks|"Bridged Ruby Elementary Blocks"]] in the Expecco API document.

== Script Actions ==

Script actions are actions written in one of the supported scripting languages, including Shell, Batch, Powershell, Node.js, Python, Ruby, GnuPlot, R, TCL, Go and others.
In contrast to "''bridged actions''", these are called as host-commands, where a new interpreter is
started for every action invokation. This has the advantage, that any existing script can be
easily used/embedded into a testsuite, but the disadvantage that the action's execution is somewhat slowed down due to the startup/shutdown times of the external interpreter, and that no state (open files, connections, objects etc.) can be passed from one action to another.

== Shell/Batch Script Elementary Block ==
An action block which is defined by a shell (or batch) script which is written in a shell command-line-interpreter language. The block's code will be executed outside expecco, by a script interpreter.
See [[ElementaryBlock_Element#Shell Script Blocks|"ShellScript Elementary Blocks"]] in the expecco [[ElementaryBlock_Element | elementary block documentation]].

== Smalltalk Programming Language ==
A pure object oriented language, with sophisticated reflection and meta programming features. See [https://en.wikipedia.org/wiki/Smalltalk Smalltalk in Wikipedia]

== Smalltalk Elementary Block ==
An action block which is defined by an execute function which is written in the Smalltalk language. The block's code is usually executed inside expecco itself, but it is also possible to define bridged Smalltalk actions, which execute inside another Smalltalk process (local or remote).
See [[Expecco_API#Smalltalk_Elementary_Blocks|"Smalltalk Elementary Blocks"]] in the Expecco API Documentation.

== Smalltalk/X ==
[https://www.smalltalk-x.de Smalltalk/X] ("''ST/X''") is the brand name of a Smalltalk programming language environment from exept / Claus Gittinger. Smalltalk/X is an ANSI compatible [https://en.wikipedia.org/wiki/Smalltalk Smalltalk] programming environment, and the base on which expecco and expeccoALM are built.

== SOAP (Simple Object Access Protocol) ==
SOAP is a remote procedure call mechanism based on XML encoded packages which are typically (but not required to be) transmitted via HTTP. The name is a euphemism: SOAP is not (no longer) simple: to be used with ease, a huge XML framework lies underneath, which extracts details for a call from a specification written in WSDL (which is also XML with a complex structure, incl. datatype definitions).

== SSDP(Simple Service Discovery Protocol) ==
Also known as UPnP, the SSDP protocol announces the availability of services via broadcast UDP packages. See [https://en.wikipedia.org/wiki/Simple_Service_Discovery_Protocol Wikipedia SSDP].

== Stderr ==
Short for "Standard Error". This is any program's standard error output stream. If running in a console window, this is typically displayed there. If running without a console window it may be lost or redirected into a logfile.
If expecco starts other programs, you have the option of redirecting their stderr to the expecco Transcript (which is the expecco console). There, this will be prefixed by "2:" and colorized in red (to indicate that this is text from stderr, as opposed to stdout). The setting is found in "''Extras''" → "''Settings''" → "''Execution''" → "''Tracing''" → "''Show Stdout/Stderr in Transcript''".

== Stdin ==
Short for "Standard Input". This is any program's standard input stream. If running in a console window, your typed input is available to the program via this stream. If running without a console window, the program will typically detect an End of File (EOF) condition when reading.
If expecco starts other programs, you have the option of providing input to the program; either on the very lowest programatic level or via an input pin in an action step.

== Stdout ==
Short for "Standard Output". This is any program's standard output stream. If running in a console window, this is typically displayed there. If running without a console window it may be lost or redirected into a logfile.
If expecco starts other programs, you have the option of redirecting their stdout to the expecco Transcript (which is the expecco console). There, this will be prefixed by "1:" and colorized in blue (to indicate that this is text from stdout, as opposed to stderr). The setting is found in "''Extras''" → "''Settings''" → "''Execution''" → "''Tracing''" → "''Show Stdout/Stderr in Transcript''".

== SUT (System Under Test) ==
The tested system.

Expecco interacts with this either in a pure [[#Black Box Test | Black Box]] fashion (i.e. only talking to external interfaces), or [[#Gray Box Test|Gray Box]] or [[#White Box Test|White Box]] fashion (some or a lot of knowledge about internals of the SUT are known).

Technically, Black Box tests interact with the SUT via (more or less official) external interfaces, such as messages, documents, communication interfaces, GUI interaction etc.

White Box tests can access data structures and interfaces internal to the SUT.

In expecco, White Box Tests are done by implanting code into the SUT. Depending on the type of technology and environment used, this code injection (or instrumentation) may be possible dynamically (Java, .NET, Python, Node.js) or has to be done statically by linking expecco-support libraries to the program (C, C++). Static binding is typically required for embedded devices, where the code is stored in non-writable memory.

Some companies (especially if hardware is involved) use the alternative term "DUT" (for "''Device under Test''") instead.

== Syntactic Sugar ==
A feature of (typically) a programming language, which does not give you more semantic features (aka "''functionality''"), but instead exists for the convenience of the user. Typically "''syntactic sugar''" designates a feature which is easier to use or shorter to write, but which could also be defined in terms of other features of the language - albeit possibly more clumsy. In expecco, a number of syntactic sugar constructs are available, which could also be described in terms of regular action blocks. For example, the "attachment step", "shell step" and even "Groovy" steps could be also defined in terms of regular elementary blocks which read a file, start a shell or talk to a JVM respectively. In the Smalltalk programming language, the brace-construct "{ expr1 . expr2 . ... exprN }" is syntactic sugar for Array-instantiation "(Array new:sz) at:1 put:expr1; ... at:n put:exprN; yourself" (btw: you don't have to understand this, to use expecco).

== Tag ==
A token (word) attached to an element. Multiple tags can be attached and are used to search, group or otherwise mark tree items, steps and other elements of the test suite. For example, you can define an icon to be shown in the left project tree if the item has a particular tag.

== Tagged Value ==
A tuple consisting of a token plus value, and an optional type. Similar to tags, these can be attached to an element. Expecco does not use tagged values (*). They are created when suites are imported from some external tools, stored with the suite and passed back transparently to the tool.
 *) this may no longer be true, by the time of reading.

== Testplan Element ==
A "''Test Plan''" or "''Testplan''" is an item in the project tree, which contains a list of test case items to be executed in sequence. A test plan's items are called "''Test Cases''" and each is implemented by an action (elementary or compound). It is also possible to drag another test plan as item into a test plan, to combine multiple tests plans into master test plans. A suite may therefore contain multiple test plans. When started without user interaction, the test plan(s) to be executed can be chosen via the command line or via a remote service request.

== [[TestSuite Element | Testsuite Element]] ==
"''Test suite''" or occasionally "''Testsuite''" is the term used for a packaged test project. It contains a collection of [[Tree_Elements| Tree Elements]] like test plans, blocks and datatypes as well as optional resources, attachments and documentation.

Test suites can be imported into other test suites and can therefore be used as libraries for reuse. When a suite is imported into another suite, all of the imported elements are visible and usable inside the importing suite.

Typically, suites are organized in a hierarchical fashion, and low-level functions (device control and access, protocols, data format handling etc.) are packaged into separate libraries, which are used by higher level component test and support actions, which are then further reused by system-, acceptance or end-to-end test scenarios.

== Transcript ==
The "''Transcript Window''" is the expecco console window, which can be opened via "''Extras''" → "''Tools''" → "''Transcript''". If open, both information messages from expecco and explicit Transcript action messages will appear there. The standard library provides a number of action blocks eg. to send messages and to clear the transcript window. Messages can also be sent to it from elementary code (both internal and bridged). If not open, those messages will be sent to "stderr" instead.

== UI (User Interface) ==
Ususally a synonym for GUI (Graphical User Interface)

== UUID (Universal Unique Identifier) ==
An identifier (aka name) which is generated to be globally unique (with very very high probability, to be precise). These are generated and attached to elements of the suite (actions, types, etc.) to ensure that expecco will always be able to correctly identify if two elements from different suites (and/or different people) represent the same thing or not.
 Technically, they are generated by generating a big number, containing a microsecond timestamp, the network address and a big random number, so that two separately generated UUIDs are very very likely to be different. Internally, expecco uses these IDs to reference other elements, thus being tolerant against name changes, layout changes and structure changes (added pins, for example), etc. Also, expecco can quickly determine if two objects (suites, actions, steps, runs, etc.) represent the same object or not.

Be aware that expecco treats two projects (as loaded from an ETS file) as two versions of the same project iff they have the same functional ID (but different version IDs). Thus, simply saving a project under a different name does not create a new project, and the two cannot be imported both into another project.

== Verdict ==

The execution's summary-outcome-status from running a test plan, test case or action. In addition to detail information (traces, data, execution time, log-messages), every execution in expecco will always return one of 4 values as a summary status:
* '''PASSED''' (green) if all went well, and the execution did not encounter any problems
* '''FAIL''' (red) the execution detected an error in the [[#SUT (System Under Test)| System Under Test (SUT)]].
:For example, it measured a wrong/unexpected value, detected invalid behavior, invalid protocol behavior etc.
:Usually, this means that the developer of the tested system is to be informed.
* '''ERROR''' (dark red) the test itself ran into some error.
:This means that during the test's execution, an error occurred inside expecco or one of the user-defined action blocks. An ERROR state does not provide information about the SUT's state; instead, the test has a problem.
:For example, if a file containing test-data could not be found or a division by zero or an index out of bounds error occurred etc.
:Usually, this means that the developer of the test is to be informed.
* '''INCONCLUSIVE''' (gray) the test had no chance to perform its testing operation(s).
:For example, if a machine could not be reached in the network, if it was not powered up or if a resource (operator, measurement device, test-device etc.) was not available, etc. Also, tests or actions which have not been executed (eg. skipped) are marked as inconclusive.
:Usually, this means that the test manager is to be informed.

The distinction is very useful as it should be kept in mind, that a test-manager/tester has to react differently depending on the reason for a test not resulting in a PASSED state:
* for a FAIL, (s)he has to inform the developer of the SUT, to fix the problem in the product.
* for an ERROR, the test-developer/analyst has to be informed to fix the problem in the test-case
* for INCONCLUSIVE, the test-manager, network administrator or test-lab-manager has to check for the availability of required devices , connections, power supply etc.
:After that, the test can be rerun without a need to contact either the product-development, nor the test-development team.

Notice, that many test systems/frameworks only provide PASS/NOT PASS information as final verdict.
 If expecco is to be integrated into such a framework, FAIL, ERROR and INCONCLUSIVE will all be treated as NON-PASS (e.g. when running under the control of Jenkins, QC, Polarion etc.)

If expecco is executed under the control of expeccoALM/Aidymo, the responsible person is chosen as per verdict and informed.

== VersionID (VID) ==
Every item within expecco (action, type, testcase, testplan, the suite itself etc.) has an associated unique identifier, which is guaranteed to be world-wide unique (a so called "''UUID''"). This guarantees, that these objects can be uniquely identified, even if renamed, or if the same name is used for an action, type etc. in two different test suites. Thus, two suites can always be merged and suites can always be imported without name conflicts.. expecco will internally always refer to any object by its ID, never by its name. The versionID is updated with every change made to an object. Thus it is guaranteed, that no two different objects have the same ID. And vice versa, that the equality (actually identity) can always be checked via the ID.

== VisualWorks ==
VisualWorks ("''VW''") is the brand name of a Smalltalk programming language environment from Cincom, a US based company. Starting with expecco 20.2, VisualWorks bridged blocks and VisualWorks GUI tests are supported by expecco.

== White Box Test ==
Designates a test which executes within the ''System Under Test'' and/or uses or refers to (but also depends on) the internals of the [[#SUT|SUT (System Under Test)]]. The test directly creates or manipulates data objects inside the SUT and/or calls internal functions. Most unit tests are typically implemented as white box tests (but not required to be so).

White Box Tests have both advantages and disadvantages.

*+ because they know the internals, more of internal details can be tested, and more of existing internal utilities can be used as utility in the test. For example, data definitions, data structures, functions and interfaces etc. can be accessed from the test system. Depending on the type of test and the available frameworks which can be "white-boxed", this may save a lot of test-development time, because those interfaces need not be reimplemented in the test system.

*- because they know the internals, they are also more reliant on them, and may also suffer from bugs in the internal frameworks. For one, if data structures and internal interfaces change, the white box test usually has to change with it. Whereas external interfaces usually remain more stable - especially if they are based on communication or data format standards. The other downside is that if internal interfaces of the SUT are heavily used, bugs in them are also injected into the test system. This may make some of the bugs invisible and undetectable to the test system. For example, if a communication data structure (say, a message or document format) is always accessed via a white-boxed SUT interface, but never actually tested physically, any bug in that framework will go unnoticed to both the SUT and to the test system. Both the SUT and the test system may see perfect data, while the data sent to the outside world may still be completely bogus.

In a real world test system, you would usually use a combination of whitebox and blackbox tests. The level of insider-knowledge of the whitebox test depends on the type of SUT, the risk analysis and trust in the frameworks being used.

It is common, that modules and components are first tested by the developers using Unit Tests (which are usually White Box Tests) and then passed on to integrators to check the interaction between modules using Black Box Tests.
But there is no sharp boundary and often a mix of both is needed in practice (aka "Grey Box Tests").

See also: [[#Black Box Test|Black Box Test]], [[#Gray Box Test|Gray Box Test]],
[https://en.wikipedia.org/wiki/White-box_testing "White-box_testing" (wikipedia) ]

== Workspace (or Notepad) ==

This is a [[Tools_Notepad/en | tool]] which is found in "''Extras''" → "''Tools''" → "''Notepad''". The name is a bit misleading and this should not be confused with the Windows "Notepad" application (therefore, it is also named "Workspace" in the documentation, although this again may lead to confusion, as "workspace" is often used with a different meaning in other contexts, such as the Eclipse IDE).

In expecco, a ''Workspace'' is a little text editor, which can also evaluate snippets written in either Smalltalk or JavaScript. It also provides a number of bulk string processing operations in its edit menu.

Whenever you have to manipulate text, a workspace is a useful edit-tool to perform such tasks (of course, you can use any other editor, if you prefer so, but startup times of external editors are often much longer, than the time it takes expecco to open its internal tools).

[[Tools_Notepad/en | Workspaces]] and all other editors in expecco (incl. the FileBrowser, Data Inspector and Elementary Action code editors) are all based on a common editor base class and have common behavior. Take a look at the popup menu to see what functionality is provided: beside the usual stuff, it can sort text, by columns, filter lines, transform lines and many more.

Especially useful are the "''Open FileBrowser''" and "''Open URL''" menu functions (found deeper down in the "''Tools''" submenu). Whenever you find a filename or URL in some text, these will quickly open the document for you.

= Abbreviations =

Commonly used abbreviations in this documentation Wiki are:

* ALM - Application Lifecycle Management
* B2B - Business to Business
* BD - (Action-) Block Description
* CB - Compound Block
* ".csf" - Connection Settings File (file suffix)
* ".csv" - Comma Separated Values File (file suffix)
* DCE - Distributed Computing Environment (an RPC mechanism)
* DLL - Dynamic Link Library (a synonym for "SO" = Shared Object); also a file suffix ".dll"
* DUT - Device Under Test
* EB - Elementary Block
* ".elf" - Expecco Log File (file suffix)
* ".ets" - Expecco Test Suite (file suffix)
* FID - Functional ID
* FTP - File Transfer Protocol (a standard internet protocol)
* GUI - Graphical User Interface; also sometimes simply "UI"
* HTTP - Hypertext Transfer Protocol (web page transfer protocol)
* QM - Quality Management
* RPC - Remote Procedure Call
* ".png" - a bitmap image file format (file suffix)
* SO - Shared Object (a synonym for DLL); also as file suffix ".so"
* SOAP - Simple Object Access Protocol (a not so simple protocol)
* SSDP - Simple Service Discovery Protocol
* SUT - System Under Test
* UI - User Interface (often actually meaning: Graphical-UI)
* URL - Unified Resource Locator (typically used with web-Browsers)
* UUID - Universal Unique Identifier
* VID - Version ID

Release Notes 25.x

2026-02-23T11:02:27Z

Sv: Änderung übernommen aus altem Wiki

See also: [[Release Notes 26.x]] 
See also: [[Release Notes 24.x]]
 

== Release 25.2 ==
*Feature: DPI awareness on Windows (i.e. when shown on a '''high-resolution monitors''') [Note: that was a lot of work...] expecco can scale views and fonts according to the scale factor set in the Windows display settings and will do so as default. Scaling by expecco is not perfect yet, e.g. icons do not get scaled. You can enable scaling in ''Settings -> Look&Feel -> More''.
*Feature: groovy version 5.0.0 (needed for Java 25 and later)
*Feature: better bulk int, float and double receiving support in the C bridge (used to be bytes only)
*Feature: Treat the test result "Pass (Warning)" as "Pass' ([[Settings_DebuggerSettings/en#Treat_test_result_"Pass_(Warning)"_as_"Pass"|Settings: DebuggerSettings]])
*Improvement: Inspector shows XML Dom if an inspected string starts with '<' and ends with '>' and is XML-parsable without error.
*Improvement: Very long index-lists (eg. 100k) are handled more gracefully
*Improvement: Bundled python3 installer updated to version 3.13.7
*Improvement: Better command and filename completion in the cmd terminal view (Windows)
*Fix: (Windows) reading the link info of a link file to a wide-char file returned wrong (non-wide) info
*Fix: blocking WebSockets with huge bulk data transfers
*Fix: transfer timeout in Bridges with huge data transfers
*Fix: (Windows): Resource Leak in Font allocation leading to running out of Windows GDI Handles (after a few thousand window openings)
*Fix: C-Bridge failed to load code when a virus checker has locked the file.
*Known Issue: When expecco is started '''for the first time after installation''', the Windows virus scan (SmartScreen) may delay the display of the expecco window.

== Release 25.1 ==
*Improvement: additional "Info" tab in inspector views
*Improvement: less memory usage in the activity log
*Improvement: better error messages and more links to settings from the activity log's error message
*Improvement: additional units and conversions in the [[PhysicalValues/en|physical values framework]]
*Improvement: more precision in the [[Numeric_Limits/en#Higher_Precision_Numbers|high precision trigonometric and math functions]]
*Improvement: WindowsAutomation: Plugin Update to FlaUI 5
*Improvement: Mobile Testing: Better Device Lock/Unlock Support
*Improvement: StandardLibrary: "File [ *CSV ]" blocks got an additional "characterEncoding" pin (useful for reading/writing e.g. utf-8 encoded CSV files)
*Improvement: ExcelLib: better documentation. Now requires the openpyxl package version >= 3.1.5.
*Improvement: better model language editor (translate and fetch-strings functions)
*Improvement: ODBCLibrary: improved compatibility with different database vendors (supports the CedarDB database)
*Feature: translate and spell check in the workspace window
*Feature: EditLock of suites loaded from expeccoALM / AIDYMO
*Feature: Start Test in expeccoALM / AIDYMO (via expecco)
*Feature: new library containing expeccoALM control actions (those from the AIDYMO menu)
*Fix: the version diff viewer (did not correctly copy changed attachment files)

Numeric Limits/en

2026-02-23T10:49:19Z

Sv: Änderung übernommen aus altem Wiki von cg, 15.2.26

This page provides some computer science basics, which are not specific to expecco.
However, in the past some users encountered problems and it is useful to provide some insight on number representations.

Expecco supports arbitrary precision integer arithmetic,
arbitrary precision fractions, arbitrary and limited precision floating point numbers in various precisions and complex numbers.
In addition, special purpose numbers for monetary and decimal presentations.

Being based on Smalltalk/X, expecco provides a complete set of number classes.

== Syntax (In Smalltalk and FreezeValues) ==

See also: "[[Smalltalk_Syntax_Cheat_Sheet]]".

====Integers (arbitrary size)====
1234567
0xFF00AA (base 16)
0b01010101 (base 2)
-0xAFFE
3r121212 (base 3)
4r123123 (base 4)

====Fractions (arbitrary integral numerator and denominator)====
(1/2)
(1/101)
(-1/3)

====ScaledDecimals ====
123s2
123.456s2

====Floats / Float64 (actually 64bit IEEE doubles)====
12.456
1e17
1.0e23
12e
.5 -- illegal
.5e -- illegal

====LongFloats / Float80 (80bit IEEE long doubles)====
12.456q
1e17q
1.0e23q
23q

====QuadFloats / Float128 (128bit IEEE quadruple floats)====
12.456Q
1e17Q
1.0e23Q

====OctupleFloats / Float256 (256bit IEEE octuple floats)====
12.456QO
1e17QO
1.0e23QO

====LargeFloats (arbitrary precision (defaults to 200bit) software floats)====
12.456QL
1e17QL
1.0e23QL

====QDoubles (4 IEEE doubles combined)====
12.456QD
1e17QD
1.0e23QD

====Complex====
1+5i
4i
1.23+5.67i

== Exact Integer Numbers ==

For integer operations, there is no overflow or error in the result for any legal operation.
I.e. operations on two big integers delivers a correct and exact result.

This is a feature of the underlying Smalltalk runtime environment and in contrast to many other programming languages (especially: Java and C) which provide int (usually 32bit) and long (usually 64bit) integer types. In expecco, you can write both in Smalltalk and in the builtin JavaScript syntax:1

2147483647 "(0x7FFFFFFF)" + 1
-> 2147483648 "(0x80000000)"

4294967295 "(0xFFFFFFFF)" + 1
-> 4294967296 "(0x100000000)"

18446744073709551615 "(0xFFFFFFFFFFFFFFFF)" + 1
-> 18446744073709551616 "(0x10000000000000000)"

Very large values can be computed:
10000 factorial
-> a huge number beginning with: 284625968091705451890641321211986889014....

Smalltalk will automatically convert any result which is too large to fit into a machine-integer into a LargeInteger (with an arbitrary number of bits) and also automatically return results converted back to a small representation, if possible.2
 Thus, although the two operands to the division in the following example are large integers,
rslt := (1000 factorial) / (999 factorial)
the result will be a small integer (since the value 1000 fits easily into a machine word).
 As a user, you do not have to care about these internals.

Hint: Therefore, you can use a [[Tools_Notepad/en |Workspace (Notepad) window]] as a calculator with arbitrary precision.

1) be aware that this only computes correct results if the elementary action is written in either Smalltalk or in the builtin JavaScript syntax. Depending on the version of the external language interpreter, it may or may not be correct, if using Java/Groovy, Python, C/C++, Node.js etc.
 
2) the integer class provides functions which operate in the limited 32 or 64 bit range. These might be useful if you have to verify results or repeat computations as returned by corresponding C or Java operations.

== Exact Fractions, ScaledDecimals and FixedDecimals ==
=== Fractions ===
When dividing integers, the "/" operator will deliver an exact result, possibly as a fraction:
5 / 3 -> 5/3
and reduce the result (possibly returning an Integer):
(5/3)*(3/2) -> 5/2
(5/3)/(3/2) -> 10/9
(5/3)*(9/3) -> 5
1000 factorial / 999 factorial -> 1000

There are also ''truncating division'' operators: "//", which returns an integer truncated towards negative infinity (i.e. the next smaller integer),
and "quo:". which truncates towards zero. "quo:" is what you'd get in Java or C.

5 // 3 -> 1
-5 // 3 -> -3

The corresponding modulo operators "\\" and "rem:" provide the remainder, such that:
(a // b) + (a \\ b) = a

The "\\" is the standard Smalltalk remainder operator; Smalltalk/X also provides "%" as an alias. Thus you can also write:
(a // b) + (a % b) = a

There is also a division operator ("quo:") which truncates towards zero, and a corresponding remainder operator ("rem:") , for which:
(a quo: b) + (a rem: b) = a

For positive a and b, the two operator pairs deliver the same result.
For negative arguments, these are different. Be aware and think about the domain of your arguments.
Be reminded that the Smalltalk remainder "%" returns different results as C or Java, when operands are negative.

In addition, the usual ceiling, floor and rounding operations are available (both on fractions and on limited precision reals):
(5 / 3) ceiling -> 2 "the next larger integer"
(5 / 3) floor -> 1 "the next smaller integer"
(5 / 3) truncated -> 1 "truncate towards zero"
(5 / 3) rounded -> 2 "round wrt. fraction >= 0.5)
(5 / 3) roundTo: 0.1 -> 1.7.
(5 / 3) roundTo: 0.01 -> 1.67

(-5 / 3) ceiling -> -1. "the next larger integer"
(-5 / 3) floor -> -2 "the next smaller integer"
(-5 / 3) truncated -> -1 "truncate towards zero"
(-5 / 3) rounded -> -2.
(-5 / 3) roundTo: 0.1 -> -1.7

Fractions print themself as "(''numerator'' / ''denominator'')".

=== ScaledDecimal ===
If you prefer a decimal representation with a defined number of fractional digits,
use ScaledDecimals (which for backward compatibility are also called "FixedPoint" (1)).

These are also exact fractions, but print differently: you can specify the number of digits to be printed and it will print itself rounded on the last digit.
In other words: the computation and internal value will be exact (as with Fractions), and therefore, no rounding errors will accumulate.
Only when printed, will the external represenatation be rounded to the specified number of decimal places.

(5 / 3) asScaledDecimal:2 -> 1.67
(5 / 3) asScaledDecimal:4 -> 1.6667

((5 / 3) asScaledDecimal:2) * 3 -> 5.00

1.2 asScaledDecimal:3 -> 1.200

Float pi asScaledDecimal:5 -> 3.14159

1) the class was previously called "FixedPoint" and the converters were called "asFixedPoint:". For compatibility with other Smalltalk dialects, these have aliases "ScaledDecimal" and "asScaledDecimal:". Both the old class name and the old operators are and will be supported in the future for backward compatibility (as aliases),
but you should use the new name, both for compatibility with other Smalltalk dialects, and to avoid confusion with FixedDecimal numbers.

=== FixedDecimal ===
As mentioned above, a ScaledDecimal keeps the exact value internally, but prints itself rounded to a given number of decimal digits.
Smalltalk/X provides an alternative class called "''FixedDecimal''" (1), which always keeps a rounded value internally. These may be better suited for monetary values, especially in computed additive sums which are printed in a table, as the sum of two FixedDecimals will always be the presented (printed) sum of two FixedDecimals. In contrast, with ScaledDecimals, you may see a sum which differs from what presented table values suggest.

For example:
v := 50.004 asScaledDecimal:2.
v printString -> '50.00'. "is actually 50.004"
v2 := v * 2.
v2 printString -> '100.01'. "is actually 100.008"

this leads to confusion, iff such numbers represent monetary values and are printed eg. in a summed-up table.

With FixedDecimals, you'll get:
v := 50.004 asFixedDecimal:2.
v printString -> '50.00'. "is actually 50.00"
v2 := v * 2.
v2 printString -> '100.00'. "is actually 100.00"

Be aware that mixed arithmetic operations will usually return an instance of the class with a higher generality, and that Floats do have a higher generality than FixedDecimals which have a higher generality than ScaledDecimals.

Thus, when multiplying a float and a fixed decimal, you'll get a float result, whereas if you multiply an integer and a fixed decimal, the result will be a fixed decimal. Finally, when multiplying a fixed decimal and a scaled decimal, the result will be a fixed decimal.

1) both names "ScaledDecimal" and "FixedDecimal" have been chosen a bit unwise, and may be confusing. However, these cannot easily be changed for backward and cross Smalltalk dialect compatibility reasons. We apologize.

== Inexact Float and Double Numbers ==

Floating point numbers are inherently inexact and almost always represent an approximated value. The error depends on the floating point number's precision, which is the number of bits with which the value is approximated. there are numbers which cannot ever be repsented as a floating point number, whatever precision is used. Even innocent looking numbers (eg. "0.1") are of this kind.

This is not a problem specific to expecco,
but inherent to the way floating point numbers are represented (in the machine). See [https://docs.oracle.com/cd/E19957-01/806-3568/ncg_goldberg.html "What Every Computer Scientist Should Know About Floating-Point Arithmetic"],
[https://people.eecs.berkeley.edu/~wkahan/Mindless.pdf "Mindless Assessments of Roundoff in Floating-Point Computation"] and [https://www-users.math.umn.edu/~arnold/disasters "Some disasters attributable to bad numerical computing"]. A very impressive example of how wrong double precision IEEE arithmetic can be is described in "[[Do_not_trust_Floating_Point]]" (1).

Floating point numbers are represented as a sum of powers of 2 (actually 1/2 + 1/4 + 1/8 +...) called the "''mantissa''" then multiplied by 2 raised to an exponent. I.e.
value = mantissa * (2 ** exponent)
with the mantissa being normalized to be a sum in the interval 0.5..1 (as listed above). And the exponent stored with an offset (called "ebias"). The minimum exponent (0) is reserved for the zero number and non-normalized tiny numbers (called "''subnormals''"); the maximum exponent is reserved for infinities and NaNs ("''not a number''"). These might be returned from some operations if invalid arguments are provided (for example, trying to take a logarithm of a negative number).

The number of exponent bits determines the largest and smallest representable magnitudes, the number of mantissa bits determines the relative error. The error depends on the value of the last mantissa bit, which depends on the exponent. This value is called "''Unit in the Last Place''" or "'ULP'" (see [https://en.wikipedia.org/wiki/Unit_in_the_last_place Wikipedia]). For a large number like 1e100, one ULP is the very large 1.94266889222573e+84, whereas for a small number like 0.5, it is 1.11022302462516e-16.

Floating point formats differ in the number of bits (single/double/extended precision etc.). 
A double precision IEEE float has 11 bits for the exponent and 53 for the mantissa (see [https://en.wikipedia.org/wiki/IEEE_754 IEEE floating point formats]).

As a rule of thumb, the error in the last bit of a double precision IEEE float is roughly 15 to 16 orders of magnitudes smaller than the magnitude of the (double precision) floating point number. The error is larger for single precision (32bit) floats and smaller for extended floats (80, 128 or more bits).

1): If you do not believe me, try the following example from one of the mentioned papers in (eg. excel) or your favourite programming language:
v := 4/3. "/ or maybe (4.0/3.0)
w := v - 1.
x := w*3.
y := x - 1.
z := (y*2)**52.

=== Limited Precision ===
Due to the limited number of bits in the mantissa, different values may end in the same floating point representation. For example, both 9223372036854776000 and 9223372036854775808 will end up being represented as the same float when converted from integer to float. The reason is that there are simply not enough bits in the mantissa.

For example:
9223372036854776000 asFloat = 9223372036854775808 asFloat
will return "true", and the difference will be zero in:
9223372036854776000 asFloat - 9223372036854775808 asFloat
in contrast to the correct result being returned when comparing/subtracting them as integers:
9223372036854776000 = 9223372036854775808.
=> false
9223372036854776000 - 9223372036854775808.
=> 192
Try it in a workspace window.

Also, many numbers (actually: most numbers) cannot be exactly represented by a finite sum of powers of 2. Such numbers will have an error in the last significant bit (actually half the last bit). When floating point numbers are added or multiplied, the result is usually computed internally with a few more bits as mantissa, and then rounded on the last bit, to fit the mantissa's number of bits. Notice that this may not be immediately obvious, because the print functions (such as printf) cheat, and round again on the last bit. Thus, a result such as 0.9999999 would still be printed as "1.0).

The situation may be relaxed slightly, by using more bits for the mantissa (and expecco gives you a choice of 32bit (called "''ShortFloat''"), 64bit ("''Float''") and 80bit ("''LongFloat''") and even more, which are mapped to corresponding IEEE floats (single, double and extended).

Repeating the above example with long floats, there are enough mantissa bits and the numbers are no longer represented or considered equal, thus:
9223372036854776000 asLongFloat = 9223372036854775808 asLongFloat
yields "false" as answer, and the computation:
9223372036854776000 asLongFloat - 9223372036854775808 asLongFloat
will give 192.0 as answer.

However, even with more bits, the fundamental restriction remains, although appearing less frequently with higher precision. But be aware that many numbers (such as 1/10, 1/5, 1/3) can '''never''' be represented exactly, no matter how many bits are used. So even the above mentioned innocent looking "0.1" is actually an approximation and wrong in the last bit.

The limited precision may lead to "strange" results, especially when operands are far apart; for example, when subtracting a very small value from a much larger one, as in:
2.15e12 - 1.25e-5
Here, the operands differ by 17 orders of magnitude, and there are not enough bits to represent the result, which will be rounded to give you 2.15e12 again.
 Thus, the comparison "2.15e12 - 1.25e-5 = 2.15e12" returns true and "2.15e12 - (2.15e12 - 1.25e-5) = 0.0", which are both obviously wrong.
 In this special case, a better result is obtained when operating with extended precision:
2.15e12 asLongFloat - 1.25e-5 asLongFloat
which gives 2149999999999.999987 as result (still incorrect due to its 64 bit mantissa, but much better).

If you are willing to trade speed for precision, you can use one of expecco's builtin higher precision representations or even the arbitrary precision representation, and compute with more bits of precision. The QDouble class provides a compromise between speed and precision, proving roughly 200 bits of precision or alternatively represents a combination of up to 4 arbitrarily valued doubles (i.e. it can represent the sum of a very large and a small number):
(2.15e12 asQDouble) - (1.25e-5 asQDouble)
(2.15e12 asQDouble) - ((2.15e12 asQDouble) - (1.25e-5 asQDouble))
Another representation supports an arbitrary number of precision bits (here 200):
(2.15e12 asLargeFloatPrecision:200) - (1.25e-5 asLargeFloatPrecision:200)
(2.15e12 asLargeFloatPrecision:200) - ((2.15e12 asLargeFloatPrecision:200) - (1.25e-5 asLargeFloatPrecision:200))
Both return the correct results 2149999999999.9999875 and 1.25e-5 respectively.

Be aware, that the higher precision and arbitrary precision operations are much slower than the ones which are directly supported by the processor (which has special hardware, usually for single, double and extended precision). Also these extended classes are still being developed and not yet released for official use (meaning they may contain bugs, especially in their trigonometric and other math functions by the time of writing).

You may use fractions,
2150000000000 - (1 / 125000)
to compute the exact result: (268749999999999999/125000)
(of course, these are less convenent to read, and should probably be presented to the end-user as ScaledDecimals.

Also, do not forget that a conversion of one number to a higher precision number cannot ''magically'' generate missing bits.
 For example, given a 32 bit floating point number which is already an approximation (i.e. the real value cannot be represented as an exact sum of powers of 2),
then the conversion will give you another such approximation, with the same error.
Thus, "0.25 asLongFloat" will give you an exact 0.25 (because 0.25 is representable), whereas "0.1 asLongFloat" will not give an exact "0.1".
Actually, the result of such a conversion will usually not give you the full possible precision.

If you need a constant with the max. precision, either enter it as such (i.e. "0.1q" instead of "0.1 asLongFloat") or read it from a string (i.e. LongFloat fromString:'0.1').

=== Floating Point Errors Propagate ===
The above rounding and last bit errors will accumulate, with every math operation performed on it (and may even do so wildly).

For example, the already mentioned 0.1 cannot be exactly represented as a floating point number, and is actually 0.099999..X with an error in the last bit (half a ULP).
 Adding this multiple times will result in a larger and larger error in the final result:
1.0 - (0.1 + 0.1 + 0.1 ...(10 times)... + 0.1) -> 1.11022302462516E-16

The print functions will try to compensate for an error in the last bit(s), showing "0.1" although in reality, it is "0.09999..." (it rounds before printing).
Thus, even though the printed representation of such a number might look ok, it will inject more and more error when the value is used in further operations (up to the point when the error accumulates out of the last bit and print will no longer be able to cheat, and the error becomes visible).

This is especially inconvenient, when monetary values or counts are represented as floats and a final sum is wrong in the penny value (and therefore, a ''real programmer'' will '''never ever use floating point numbers to represent monetary values'''!).

 As an example, try to sum an array consisting of 10 values:
(Array new:10 withAll:0.1) sum printString
which results in "1.0" due to print's cheating,
 whereas:
(Array new:100 withAll:0.1) sum printString
will show '9.99999999999998' (i.e. the error accumulated to a value too big for print's cheating to compensate).

Expecco (actually the underlying Smalltalk) provides additional number representations which are better suited for such computations: Fraction, ScaledDecimal and FixedDecimal (in other systems, ScaledDecimals are also called "''FixedPoint''" numbers, and expecco knows that as an alias).

These are exact fractions internally, but use different print strategies: Fractions print as such (i.e. '1/3', '2/17' etc.) whereas ScaledDecimal and FixedDecimal numbers print themself as decimal expansion (i.e. '0.33' or '0.20'). ScaledDecimal constant numbers can be entered by using "s" instead of "e" (i.e. '1.23s' defines a scaled decimal with 2 and '1.23s4' which will print 4 valid digits after the decimal point).

No such rounding errors are encountered, if fractions are used:
1 - ((1/10) + (1/10) + (1/10) ...(10 times)... + (1/10)) -> 0
or if ScaledDecimal numbers are used:
(Array new:100 withAll:0.1s) sum printString -> '10.0'

=== Floating Point Number Comparison ===
Be aware of such errors, and do not compare floating point numbers for equality/inequality.

As a concrete example, try:
(0.2 + 0.1 - 0.3) = 0
which will return <code>false</code> and if you print "0.2 + 0.1 - 0.3", you might get something like: "5.55111512312578e-17".
 Even increasing the precision does not really help; if we went to 200bits precision, we'd still get a small error:
(0.2QL + 0.1QL - 0.3QL) printString
gives "-3.111507638930570853572...e-61"

The problem also occurs when comparing numbers with different precision. For example, consider that a float32 value is to be compared against a constant. The float32 might be read from a file or provided by a measurement device via any communication mechanism.
If we compare it against a higher precision value, the missing bits in the shorter float are filled with zeros. Thus:
(Float32 readFrom:'0.125') = 0.125
leads to a <code>true</code> value, whereas:
(Float32 readFrom:'0.123') = 0.123
returns <code>false</code>.
 The reason for this is that 0.125 can be represented as exact float in both float32 and float64 formats, whereas 0.123 is non-exact and has repeated binary digits.
Its representation as float64 is:
0 01111111011 1111011111001110110110010001011010000111001010110000
and:
0 01111011 11110111110011101101101
as float32.
When comparing, the float32 is expanded to:
0 01111011 111101111100111011011010000000000000000000000000000000
which is obviously different.

Instead of comparing against a constant, either use range-compares and/or use the special "''compare-almost-equal''" functions, where the number of bits of acceptable error can be specified (so called: "''ULPs''"). Expecco provides such functions both for elementary code and in the standard action block library.

Again, for this reason, do not compute money values using floats or doubles.
Instead, use instances of ScaledDecimal.
Otherwise you might loose a cent/penny here and there, if you use floats/doubles on big budgets.

With scaled decimals, the result is correct:
0.1s + 0.2s - 0.3s = 0. => true
and:
(0.1 asScaledDecimal + 0.2 asScaledDecimal - 0.3 asScaledDecimal) printString => 0.00

Find further insight [https://randomascii.wordpress.com/2012/02/25/comparing-floating-point-numbers-2012-edition/ here]

=== Limited Range of Float and Double Numbers ===

Floating point numbers also have a limited range; there are smallest and largest representable values.
 
In expecco, the default float format is IEEE double precision format (called "''Float''" or "''Float64''" in expecco).
Numbers with an absolute value greater than 1.79769313486232E+308 will lead to a +INF/-INF
(infinite) result, and numbers with absolute value smaller than 2.2250738585072E-308 will be zero.

For IEEE single precision floats (called "''ShortFloat''" or "''Float32''" in expecco), the range is much smaller, and for IEEE extended precision (called "''LongFloat''" or "''Float80''" in expecco), the range is larger.

You can ask the classes (or its instances 1) for their limits, with:
* fmin (smallest representable number larger than zero)
* fmax (largest representable number),
* emin (smallest exponent; binary)
* emax (largest exponent binary),
* precision (bits in mantissa, incl. any hidden bit),
* decimalPrecision (digits when printed),

remember Float is the same as Float64
Float fmin -> 2.2250738585072E-308
Float fmax -> 1.79769313486232E+308
Float emin -> -1022
Float emax -> 1023
Float precision -> 53
Float decimalPrecision -> 15

remember ShortFloat is an alias for Float32
ShortFloat fmin -> 1.175494e-38
ShortFloat fmax -> 3.402823e+38
ShortFloat emin -> -126
ShortFloat emax -> 127
ShortFloat precision -> 24
ShortFloat decimalPrecision -> 7

remember LongFloat is an alias for Float80
LongFloat fmin -> 3.362103143112093506E-4932
LongFloat fmax -> 1.189731495357231765E+4932
LongFloat emin -> -16382
LongFloat emax -> 16383
LongFloat precision -> 64
LongFloat decimalPrecision -> 19

QuadFloat is an alias for Float128
Float128 fmin -> 3.36210314311209350626267781732e-4932
Float128 fmax -> 1.18973149535723176508575932662e+4932
Float128 emin -> -16382
Float128 emax -> 16383
Float128 precision -> 113
Float128 decimalPrecision -> 34

OctaFloat is an alias for Float256
Float256 fmin -> 2.48242795146434978829932822291387172...5329791379e-78913
Float256 fmax -> 1.61132571748576047361957211845200501...7125049607e+78913
Float256 emin -> -262142
Float256 emax -> 262143
Float256 precision -> 237
Float256 decimalPrecision -> 71

QDouble fmin -> same as float64
QDouble fmax -> same as float64
QDouble emin -> same as float64
QDouble emax -> same as float64
QDouble precision -> 204
QDouble decimalPrecision -> 61

aLargeFloat fmin -> 0.0 arbitrary small 1
aLargeFloat fmax -> inf arbitrary large
aLargeFloat emin -> -inf arbitrary small
aLargeFloat emax -> inf arbitrary large
aLargeFloat precision -> 200 default; configurable
aLargeFloat decimalPrecision -> 60 default; configurable

Remember that the name "Float" refers to "Float64", which is called "double" in the C language.
And also remember that the name "ShortFloat" refers to "Float32", which is called "float" in C.
And finally, the name "LongFloat" refers to "Float80", which is called "long double" in C.

As a consequence of the limits, you cannot compute very large numbers using any of the CPU supported floats, and you will have to use one of the software computed float representations.
 For example trying to compute the number of decimal digits of a huge number:
10000 factorial asFloat log10 -> INF
I.e. it returns infinity, because 10000 factorial asFloat already returns INF.
(it could have been converted with "asFloatChecked" which raises an exception in that situation, which is probably a good idea to do.
However, the regular asFloat conversion uses the underlying machine's CPU support, which returns INF, and is similar to the behavior in other programming languages).

In contrast, the integer computation does it:
10000 factorial log10 -> 35659.454274

Again: this is not a problem specific to expecco,
but inherent to the way floating point numbers are represented in the CPU.

1)because LargeFloats have an individual number of precision (per instance), you should ask the instance, not the class. The class will return the default values (which are valid for 200 bits of resolution).

=== Speed of Operations ===
Machines have builtin floating point math operations, which usually work fastest in single or double precision (actually, some modern machines work faster in double than in single precision).

Unless you have special precision needs, it is best to stick with double precision which is also portable across machines.
Therefore, double precision floats (aka "''double''") is the default and simply named "''Float''" in Smalltalk/X (and therefore also in expecco) 1.

1)The reason for calling them "Float" is historic. There exist smalltalk dialects where Floats are 32bit IEEE floats, and others where they are 64bit. To be able to import code from either dialect, Smalltalk/X uses double precision for "Float". To make you intention clear, it is recommended to use the explicit names "Float32", "Float64" etc.

== Trigonometric and other Math Functions ==

Some trigonometric and other math functions (sqrt, log, exp)
will first convert the number to a limited precision real number (a C-double),
and therefore may have a limited input value range and also generate inexact results.

For example, you will not get a valid result for:
10000 factorial sin
because it is not possible to represent that large number as real number.
(expecco will signal a domain error, as the input to sin will be +INF)

Also, the result from:
(9 / 64) sqrt
will be the (inexact) 0.375 (a double), instead of the exact 3/4 (a fraction).
(this might change in a future release and provide exact results if both numerator and denominator are perfect squares)

You can however first convert to a higher precision float and then apply the function. These will compute using a Taylor series or Newton approximation taking the number's precision into account:

2 sqrt
=> 1.4142135623731 (computed with float64 precision)

2 asFloat128 sqrt
=> 1.41421356237309504880168872421

2 asFloat256 sqrt
=> 1.41421356237309504880168872420969807856967187537694807317667973799073

(2 asLargeFloatPrecision:500) sqrt
=> 1.4142135623730950488016887242096980785696718753769480731766797379907324784621070388503875343276415727350138462309122970249248360558507372126441214971

== Complex Results==
By default, Smalltalk/X will raise an error if the result of a function with a real operand would return a complex result.
 For example, computing the square root of a negative number as in:
-2 sqrt
will raise an "ImaginaryResultError".

However, this is a ''proceedable exception'' 1, which can be caught and if the handler proceeds, a complex result is returned:
rslt := ImaginaryResultError ignoreIn:[ -2 sqrt ].
for readability, there is also an alias called "trapImaginary:" in the number class:
rslt := Number trapImaginary:[ -2 sqrt ]

Both of the above would return the complex result:
(0+1.4142135623731 i)

Thus,
rslt := -2 sqrt squared
will result in an exception, whereas:
rslt := Number trapImaginary:[ -2 sqrt squared]
will generate a result of "-2.0".

All operations within "[" .. "]" which would produce an ImaginaryResultError will return a complex. Thus you can write:
Number trapImaginary:[
|num1 num2|

num1 := -2 sqrt.
num2 := -3 sqrt.
Transcript showCR: (num1 + num2).
]
and "(0+3.14626436994197i)" will be shown.

1)Proceedable exceptions are among the unique features of the Smalltalk programming language; exceptions may be raised as being proceedable, and an exception handler may then "proceed" and provide an alternative return value from the failed operation. This mechanism is used here, where the exception handler - if pesent - can decide to return an imaginary result.

== Undefined Results, NaN and Domain Errors ==
Similar to the way imaginary results are handled, some operations are not defined for certain values (values outside the function's domain).
 For example, the receiver of the <code>arcSin</code> operation must be in [-1 .. 1].

By default, these situations are also reported by raising an error, and therefore:
-2 arcSin
will raise such a "DomainError".

Similar to the above, this can be handled, although no useful value will be provided (in the above case, NaN (Not a Number) will be returned:
rslt := DomainError ignoreIn:[ -2 arcSin ]
or:
rslt := Number trapDomainError:[ -2 arcSin ].

Both of the above would generate a NaN as result.

Notice that if such a NaN is used in other arithmetic operations, either more exceptions or other NaNs will usually be generated (depending on the exception being handled or not).
 Thus:
rslt := Number trapDomainError:[ -2 arcSin sin ].
will also generate a NaN as result.

You can check for valid results with:
''aNumber'' isNaN - true for NaN
''aNumber'' isInfinite - true for infinities
''aNumber'' isPositiveInfinity - true for +inf
''aNumber'' isNegativeInfinity - true for -inf
''aNumber'' isFinite - false for NaN or infinities (i.e. true for valid numbers)

== Overflow ==
When an operation's arguments are OK, but the result falls outside the range of representable numbers [fmin..fmax], you will get an infinite result 1). Further operations on these might produce more infinities or a NaN ("''Not a Number''").
This may be especially troublesome, if a final result gets corrupted due to an intermediate computation, as in:
a := 1e+10.
b := 1e+300.
c := 1e+20.
d := 1e+300.

rslt := (a*b) / (c*d)
-> NaN
Here, the final result is certainly representable, but the intermediate values (1e10 * 1e300) are out of the Float range [2.225E-308 .. 1.796e+308]. Thus, the computation will be:
a := 1e+10.
b := 1e+300.
c := 1e+20.
d := 1e+300.

(a*b) -> INF
(c*d) -> INF
INF / INF -> NaN
If the above intermediates are computed with a higher precision, the final result will be correct:
a := 1e+10.
b := 1e+300.
c := 1e+20.
d := 1e+300.

t := (a asLongFloat * b asLongFloat) / (c asLongFloat * d asLongFloat).
rslt := t asFloat
-> 1e-10

Of course, with LongFloats, the problem is only shifted towards larger numbers; as soon as the temporary result cannot be represented by a LongFloat:
a := 1q+100.
b := 1q+4900.
c := 1q+200.
d := 1q+4900.
rslt := (a * b) / (c * d).
-> NaN

then, you may use arbitrary precision LargeFloat numbers:
t := (a asLargeFloat * b asLargeFloat) / (c asLargeFloat * d asLargeFloat).
rslt := t asFloat.
-> 1e-100

1) that is the current default behavior. Future versions may allow enabling exceptions in this situation, if there are customer requests. However, as most other programming languages behave similar in these situations, most programmers are aware of these pitfalls and avoid such problems.

== Different Results on Different CPUs ==

Since FLOAT32 and FLOAT64 arithmetic is performed by the underlying CPU hardware,
different results (in the least significant bit) may be returned from math operations on different CPUs or even different versions (steppings) of the same CPU architecture.

This applies especially to trigonometric and other math functions. Therse are computed by Power- or Taylor-series or Newton approximations with different algorithms on different systems, leading to different results.
 Be prepared for this, and use the "''almost-equal''" comparison functions when results are to be verified.

== Summary of Higher Precision Numbers ==

Expecco supports various inexact real formats, with different precision (i.e. number of mantissa bits).
Some of those classes have alias names; these are provided to make Smalltalk/X code portable to other Smalltalk dialects
(however, within expecco, you will probably not care, as it is not planned to port it to another dialect).

Name Overall Exponent Mantissa Decimal fmin ST/X ANSI-ST ST80/VW IBM VA-ST
Size Size Size 1) Precision fmax Name Name 4) Name 4) Name 4)
Bit Bit Bit Digits

IEEE single 32 8 24 6 1.175494e-038 ShortFloat FloatE Float -
3.402823e+038 FloatE
Float32

IEEE double 64 11 53 15 2.225074e-308 Float FloatD Double Float
1.797693e+308 FloatD
Float64
Double

IEEE extended 80/128 15 64/112 19/34 3.362103e-4932 LongFloat FloatQ 2) - -
1.189731e+4932 FloatQ
Float80
or Float128

quad double 4*64 11 204 60 1.175494e-038 QDouble - 3) - -
3.402823e+038

IEEE quadruple 128 15 112 34 3.362103e-4932 QuadFloat - 3) - -
1.189731e+4932 Float128

IEEE octuple 256 19 236 71 2.482427e-78913 OctaFloat - 3) - -
1.611325e+78913 Float256

IEEE arbitrary any any any any any IEEEFloat - 3) - -
any

large float any any any any any LargeFloat - 3) - -
any

(1) mantissa incl. any hidden bit (normalized floats)

(2) LongFloats use the underlying CPU's long double format. On x86/x64 machines, LongFloats are represented as 80bit extended floats with 64bit mantissa; on other CPUs these might be represented as 128bit quadFloats with 112 bit mantissa (eg. a SPARC CPU does this).

(3) these are still been developed and provided as a preview feature without warranty (meaning: they may be buggy at the moment; let us know if you need them).

(4) different Smalltalk dialects use different precisions for their floating point numbers: ST80/VW Floats are IEEE singles, V'Age Floats are IEEE doubles and ST/X Floats are IEEE doubles. VW refers to Float64 as Double. Later, the ANSI standard defined FloatE, FloatD and FloatQ as aliases. You can use either interchangable in expecco.

Notice that the use of any but double precision floats (which are directly supported by the machine) may come at a performance price.
 The speed of operations degrades from double -> single -> extended -> ieee128 -> quad double -> ieee256 -> ieee arbitrary - largeFloat.
 This is especially true for the trigonometric and math functions, where both more iterations are needed to get to the desired precision in the series computations and the individual operations are also much slower.

Be aware that LargeFloats are super precise, but also super slow.

== Constants ==
Some well known and common constants can be acquired by asking a number class such as the Float class:

Float pi -> pi (3.14159...)
Float halfPi -> pi / 2
Float twoPi -> pi * 2
Float phi -> phi (golden ratio 1.6180...)
Float sqrt2 -> square root of 2 (1.4142...)
Float sqrt5 -> square root of 5 (2.2360...)
Float ln2 -> natural log of 2 (0.69314...)
Float ln10 -> natural log of 10 (2.30258...)
Float e -> e (2.718281...)

Each number class will return a representation of that constant with its precision. I.e. if you ask the Float class for the constant "pi", you'll get a pi with roughly 15 digits precision, whereas if you ask QDoubles, a more accurate representation will be returned.
ShortFloat pi (= Float32 pi) -> 3.141593
Float pi (= Float64 pi) -> 3.14159265358979
LongFloat pi (= Float80 pi) -> 3.141592653589793238
QuadFloat pi (= Float128 pi) -> 3.1415926535897932384626433832795027
QDouble pi (= QDouble pi) -> 3.1415926535897932384626433832795028841971693993751058209749446
OctaFloat pi (= Float256 pi) -> 3.14159265358979323846264338327950288419716939937510582097494459230781639
LargeFloat pi (= LargeFloat64 pi) -> 3.1415926535897932384626433832795028841971693993751058209749445923078164 [many more digits...]

== Examples ==

Code examples in Smalltalk syntax. Notice the float precision qualifiers:
'q' -> longFloat (= IEEE extended precision = Float80)
'Q' -> quadFloat (= IEEE quadruple precision = Float128)
'QO' -> octaFloat (= IEEE octuple precision = Float256)
'QD' -> qDouble
'QL' -> longFloat (arbitrary precision)

Square Root:
2.0 sqrt asShortFloat -> 1.414214
2.0 sqrt -> 1.4142135623731
2.0q sqrt -> 1.414213562373095049
2.0Q sqrt -> 1.4142135623730950488016887242097
2.0QD sqrt -> 1.4142135623730950488016887242096980785696718753769
2.0QO sqrt -> 1.41421356237309504880168872420969807
8569671875376948073176679737990732
(2.0QL precision:200) sqrt -> 1.41421356237309504880168872420969807
8569671875376948073176679
(2.0QL precision:400) sqrt -> 1.41421356237309504880168872420969807
85696718753769480731766797379907324
78462107038850387534327641572735013
846230912297025
(2.0QL precision:800) sqrt -> 1.41421356237309504880168872420969807
85696718753769480731766797379907324
78462107038850387534327641572735013
84623091229702492483605585073721264
41214970999358314132226659275055927
55799950501152782060571470109559971
605970274...

Precision value from Wolfram: 1.41421356237309504880168872420969807
85696718753769480731766797379907324
78462107038850387534327641572735013
8462309122970249248360...

Cubic Root:
2.0 cbrt asShortFloat -> 1.259921
2.0 cbrt -> 1.25992104989487
2.0q cbrt -> 1.259921049894873165
2.0Q cbrt -> 1.25992104989487316476721060727823
2.0QD cbrt -> 1.25992104989487316476721060727822835
05702514647015
2.0QO cbrt -> 1.25992104989487316476721060727822835
05702514647015079800819751121553
(2.0QL precision:200) cbrt -> 1.25992104989487316476721060727822835
0570251464701507980081975
(2.0QL precision:400) cbrt -> 1.25992104989487316476721060727822835
05702514647015079800819751121552996
76513959483729396562436255094154310
256035615665259
(2.0QL precision:800) cbrt -> 1.25992104989487316476721060727822835
05702514647015079800819751121552996
76513959483729396562436255094154310
25603561566525939902404061373722845
91103042693552469606426166250009774
74526565480306867185405518689245872
516764199373709695098382...

Wolfram: 1.25992104989487316476721060727822835
05702514647015079800819751121552996
76513959483729396562436255094154310
2560356156652593990240...

Exponentiation:
2.0 exp asShortFloat -> 7.389056
2.0 exp -> 7.38905609893065
2.0q exp -> 7.389056098930650227
2.0Q exp -> 7.38905609893065022723042746057499
2.0QD exp -> 7.38905609893065022723042746057500781
31803155705518
2.0QO exp -> 7.38905609893065022723042746057500781
318031557055184732408712782252257266
(2.0QL precision:200) exp -> 7.38905609893065022723042746057500781
3180315570551847324087123
(2.0QL precision:400) exp -> 7.38905609893065022723042746057500781
31803155705518473240871278225225737
96079057763384312485079121794773753
161265478866123
(2.0QL precision:800) exp -> 7.38905609893065022723042746057500781
31803155705518473240871278225225737
96079057763384312485079121794773753
16126547886612388460369278127337447
83922133980777749001228956074107537
02391330947550682086581820269647868
208404220982255234875742...

Wolfram: 7.38905609893065022723042746057500781
31803155705518473240871278225225737
96079057763384312485079121794773753
16126547886612388460369278...

== See Also ==
[[Number API Functions]]

Number API Functions

2026-02-23T10:48:19Z

Sv: Änderung übernommen aus altem Wiki von cg, 15.2.26

This document lists most useful (and most often needed) number functions.
Be aware, that there are many more to be found in either the class references or via the builtin [[Tools_ClassBrowser/en | class browser]].

See also [[Expecco_API/en#Numbers | "Numbers"]] in [[Expecco_API]].
 
Reference: [http://live.exept.de/ClassDoc/classDocOf:,Integer Integer], [http://live.exept.de/ClassDoc/classDocOf:,Float Float], [http://live.exept.de/ClassDoc/classDocOf:,Fraction Fraction], [http://live.exept.de/ClassDoc/classDocOf:,FixedPoint ScaledDecimal], [http://live.exept.de/ClassDoc/classDocOf:,Complex Complex]
which all inherit from
[http://live.exept.de/ClassDoc/classDocOf:,Number Number]

[[Useful API Functions | Back to Useful API Functions]]

=== Literals (i.e. Constant Numbers) ===

Literals are constants as written in elementary Smalltalk code and also given as freeze value to a pin or initial value to a variable.

===== Integer Literals =====
1234
1234567890123456789012345678901234567890
-123456789012345678901234567890
0xaffe or 16rFFAA (hex in C/JSON or Smalltalk syntax)
-0xaffe or 16r-FFAA (negative hex in C- or Smalltalk syntax)
0b101010 or 2r0101 (binary in C/JSON or Smalltalk syntax)
0o377 or 8r377 (octal)
<''N''>rXXX (arbitrary radix N)
Integer constant; decimal, hex, binary, octal or any base ''N''; integers may be arbitrary long

===== Floating Point Literals (Limited Precision Rationals) =====
0.5
1e5
-1.2e-3
12.6789q or 1.7e-21q (extended precision)
3.6789f or 2.67e5f (single precision)
Float constant; actually IEEE double precision; use "q" instead of "e" for extra precision (extended IEEE floats) or "f" for single/less precision.

In addition to single, double and extended floats, additional precision representations ('Q', 'QD', 'QL' and 'QO') are available (see below).
3.6789Q or 2.67e5Q (float128)
3.6789QO or 2.67e5QO (float256)
3.6789QD or 2.67e5QD (quad double representation)
3.6789QL or 2.67e5QL (largeFloat representation)

===== Fraction Literals =====
(4/3)
(523423432/3)
(-5/3)
Fraction constants (numerator / denominator); these are exact

===== Scaled Decimal Literals =====
123.456s2
-33.4s2
100s2
Scaled decimal; the number after the "s" defines the print-scale. The above numbers print themself rounded to 2 fractional digits e.g. "123.46", "-33.40" or "100.00" (although internally, the full precision is kept for further operations).

===== Complex Number Literals =====
(4+3i) or (-5+2i) or (-10-4i)
(4.3+3.1i) or (4.3 + 1i)
5.0 i or 5i
Complex number (real part / imaginary part)

== Wellknown Constant Numbers ==
A few common constants are known by name.
They are answered by corresponding getter messages sent to the number class of which you want the constant (i.e. these return the constants in their respective precision):

:Float '''pi'''
::pi as IEEE double precision number

:FloatD '''pi'''
:Float64 '''pi'''
::the same as above (FloatD and Float64 are aliases for the default float class "Float")
:FloatQ '''pi'''
:Float80 '''pi'''
::pi as IEEE extended precision number (FloatQ and Float80 are aliases for the extended float class also known as "LongFloat")
:FloatE '''pi'''
:Float32 '''pi'''
::pi as IEEE single precision number (FloatE and Float32 are aliases for the single precision float class also known as "ShortFloat")
:Float128 '''pi'''
::pi as IEEE quadruple precision number
:Float256 '''pi'''
::pi as IEEE octuple precision number

:<FloatClass> '''ln2'''
:<FloatClass> '''ln10'''
:
:<FloatClass> '''sqrt2'''
:<FloatClass> '''sqrt3'''
:<FloatClass> '''e'''
:
:<FloatClass> '''NaN''', '''infinity''' and '''negativeInfinity'''

Take a look at the class in a class browser for additional useful constants.

== Float Representations ==
=== Standard Float Representations ===
For traditional reasons, the name "''Float''" refers to IEEE double precision floating point numbers in expecco, whereas IEEE single precision floats are called "''ShortFloats''".
For more readability, the float classes can also be referred to via their aliases:
:Float32 = FloatE (=ShortFloat),
:Float64 = FloatD (=Float)
:Float80 = FloatQ (=LongFloat).

There is usually no need to explicitly use or refer to ShortFloats (or FloatEs): modern CPUs usually process them as fast as doubles. However, you may need them to either simulate single precision arithmetic (which may show different convergence behavior in some series computations) or to exchange binary data with other systems (i.e. to generate a byteArray containing the float's bits or to write a single precision float's bits to a stream).

====== Float / FloatD / Float64 ======
Floats (double precision IEEE floats) are stored in 64 bits, having an 11-bit exponent and a 52+1 bit mantissa (1 bit is hidden due to normalization). This gives roughly 15 digits of precision. This is the default used, if you write a float number in the code.

====== ShortFloat / FloatE / Float32 ======
ShortFloats (single precision IEEE floats) are stored in 32 bits, having an 8-bit exponent and a 23+1 bit mantissa (1 bit is hidden due to normalization). This gives roughly 7 digits of precision.

====== LongFloat / FloatQ / Float80 ======
LongFloats (extended precision IEEE floats) are stored in 80 bits, having a 15-bit exponent and a 64 bit mantissa. This gives roughly 19 digits of precision.

By Default, Floats print themself with either a decimal point or an exponent indicator 'e', e.g. "0.5", "10.0" or "1.3e3". However, there are a number of functions provided to print numbers in other formats.

=== Experimental Extra Float Representations ===
For background information on why you should not trust IEEE floating point arithmetic, and why you may need more precision in some situations,
please read the article "[[Do not trust Floating Point]]".

Expecco (actually its underlying Smalltalk engine) includes versions for higher precision floats. Please be careful in using them for production code, as they are still considered being "''work in progress''", and may or may not work as expected. Especially trigonometric and other math functions are known to be slightly less precise than expected. Please use those with extra care and report any bugs.

For now, we recommend the use of LargeFloat instead of QuadFloat/OctaFloat or QDouble if large precision is needed.

====== LargeFloat ======
LargeFloats use an arbitrary (configurable) number of bits to represent floats with any precision. They are completely software emulated, which makes most operations much slower than with other floats. In other languages, these are sometimes called "''BigFloat''".

Usage is similar to QDoubles as described below. However, when creating aLargeFloat, you have to give the desired precision (in bits) as argument:
1.0 asLargeFloatPrecision:200
or in decimals:
1.0 asLargeFloatDecimalPrecision:100
If no precision is given, a default prcision of 200 bits is used, as e.g. by:
1.0 asLargeFloat

You will get roughly 1 decimal digit of precision per 3 bits (i.e. the above 200bit precision corresponds to a decimal precision of roughly 60 digits). Be aware, that a non-present precision cannot be 'magically' reconstructed. Thus a float64 like 0.1 (which cannot be represented exactly) will remain inexact in the original number of bits. If in doubt, convert from a string representation (i.e. <code>LargeFloat fromString:'0.1'</code> or <code>LargeFloat fromString:'0.1' precision:200</code>).

Example (1):
45 degrees sin
=> 0.707106781186547
(a float with roughly 15 digits precision)

(45 asLargeFloatPrecision:200) degrees sin
=> 0.70710678118654752440084436210484903928483593768847403658834

and back:
(45 asLargeFloatPrecision:200) degrees sin arcSin radiansToDegrees
=> 45.0
1) the meaning of "degrees" is described in the [[PhysicalValues/en#Angle|"Physical Values"]] document.

====== QDouble / FloatQD ======
QDoubles use 4 double precision floats (holding the unevaluated sum of 4 doubles) to represent a float with roughly 200 bits of precision (actually often more, depending on the values).
The theory is described in "Library for Double-Double and Quad-Double Arithmetic" by Yozo Hida† Xiaoye S. Li‡ David H. Bailey May 8, 2008, and the ope source code is found on github.

QDoubles are able to represent sums/differences of up to 4 a very distant doubles (eg. a very large plus a very small value). For example with regular floats (i.e. IEEE double precision):
(1e200 + 1e-15) - 1e200
=> 0.0
the small value is lost. Whereas with QDoubles as in:
(1e200 asQDouble + 1e-15) - 1e200
=> 1e-15
it is preserved.

QDoubles are thus able to represent sums of wildly distant numbers.
With regular floats, the following computations all deliver a wrong result:
1e200 + 1e-15 + 1e-100
=> 1E+200 (loosing 1e-15 + 1e-100)

(1e200 + 1e-15 + 1e-100) - 1e200
=> 0 (wrong; lost 1e-15 + 1e-100)

(1e200 + 1e-15 + 1e-100) - 1e200 - 1e-15
=> -1e-15 (wrong)

(1e200 + 1e-15 + 1e-100) - 1e200 - 1e-100
=> -1E-100 (wrong)

(1e200 + 1e-15 + 1e-100) - 1e200 - 1e-15 - 1e-100
=> -1E-015 (wrong)
whereas with QDoubles, we get:
1e200 asQDouble + 1e-15 + 1e-100
=> 1E+200 (printed, actual value is correct)

(1e200 asQDouble + 1e-15 + 1e-100) - 1e200
=> 1.0e-15 (correct)

(1e200 asQDouble + 1e-15 + 1e-100) - 1e200 - 1e-15
=> 1E-100 (correct)

(1e200 asQDouble + 1e-15 + 1e-100) - 1e200 - 1e-100
=> 1E-015 (correct)

(1e200 asQDouble + 1e-15 + 1e-100) - 1e200 - 1e-15 - 1e-100
=> 0.0 (correct)
or another example:
t := 1234 + 0.567890 + 0.00000012345 + 0.000000000006789.
a := t - 1234. "/ 0.567890123456891 (mhmh ?)
b := a - 0.567890. "/ 1.23456891154561E-07 (mhmh ?)
c := b - 0.00000012345. "/ 6.89115456081139E-12 (mhmh ?)
d := c - 0.000000000006789. "/ 1.0215456081139E-13 (wrong)
whereas:
t := 1234 asQDouble + 0.567890 + 0.00000012345 + 0.000000000006789.
a := t - 1234. "/ 0.56789012346 (mhmh ?)
b := a - 0.567890. "/ 1.23456789e-7 (mhmh ?)
c := b - 0.00000012345. "/ 6.789E-12 (correct)
d := c - 0.000000000006789. "/ 0.0 (correct)

However, there is no insurance, that bits are not lost. If one of the operands already needs all four doubles (because it cannot be represented exactly as a sum of 3 floats), bits from the second operand may be lost. For example:
1e100 asQDouble + 1
will result in 1e100 (without the one), because 1e100 already uses all bits (i.e. all 4 doubles) of the QDouble.
If you need the full precision, you may have to use LargeFloats, although the processing overhead will usually be larger then.

Due to the extra processing overhead, operations are slower than with doubles or extended doubles.

:Attention: Strange results seem to be generated when regular floats are converted to QDoubles iff the original float was not representable as an exact number. For example, adding the float 0.2 to the QDouble 1.0QD will result in a number different from 1.2QD, because the original 0.2 had an error in its last bit, which gets now visible when converted to QDouble.
Better use LargeFloat instead, if more precision is needed.

====== QuadFloat / Float128 ======
QuadFloats use the 128 bit IEEE quadruple precision binary128 format, with 15 exponent bits, providing roughly 34 digits of precision.
 QuadFloats are software emulated, and thus computations are slower than with regular floats.

:Attention: Do not use Quadfloats for now, except to convert from/from binary data. Currently, they may return slightly incorrect results for trigonometric operations (rounding modes are not correctly implemented). Use  LargeFloat if more precision is needed.

====== OctaFloat / Float256 ======
OctaFloats use the 256 bit IEEE octuple binary256 format, with 19 exponent bits, providing roughly 70 digits of precision and a larger range for the exponent.
 OctaFloats are also software emulated by a flexible arbitrary precision IEEE algorithm, and slower than QuadFloats and QDoubles (actually often even slower than LargeFloats below).

:Attention: Do not use Octafloats for now, except to convert from/from binary data. Currently, they may return slightly incorrect results for trigonometric operations (rounding modes are not correctly implemented). Use  LargeFloat if more precision is needed.

== Fractions ==
Fractions are returned from integer divisions; i.e. when both "''a''" and "''b''" are integers and "''a'' / ''b''" does not result in an integral result.
 Fractions are exact; no precision is lost. Results of arithmetic operations are reduced and possibly yield integers. Thus:
(1/3) * (1/3)
=> (1/9)
and:
(1/3) * 9
=> 3 (an exact integer)

Fractions print themself as "(''a'' / ''b'')".
 They are computed in software and thus usually slower than float operations (especially with huge numerators/denominators).

== Scaled Decimals ==
These '''print themself rounded''' to a specified number of fractional digits (the so called ''scale''). For example, "<code>1234.567 asScaledDecimal:2</code>" will print itself as "1234.57" (i.e. rounded).
 However, internally the full precision is kept, so an arithmetic operation will still deliver a correct result.

Scaled decimals are perfect to present values to a user or in a report in a "human friendly" rounded format.
 Example:
a := 1234.567 asScaledDecimal:2.
a print.
=> '1234.57'

b := 23.007 asScaledDecimal:2
b print.
=> '23.01'

(a + b) print.
=> '1257.57'

This is because the sum (a+b) is actually (1234.567 + 23.007 = 1257.574), which is printed as '1257.57' (rounded).

 This also works for Fractions:
 Fraction example:
c := (1/3) asScaledDecimal:2.
c print.
=> '0.33'

d := (2/3) asScaledDecimal:2
d print.
=> '0.67'

(c + d) print.
=> '1.00'

Be aware that the output will look strange (i.e. look wrong) if monetary values are presented this way, e.g. on an invoice's summation. Here, we'd expect a sum of amounts to be the sum of previously listed values (think of sales tax being computed, giving a rounded Cent-value).
 See FixedDecimal below for a better solution.

ScaledDecimals can be rounded to their scale, so that further computation are taking that value.
Thus taking the above values rounded:
a := a roundedToScale.
b := b roundedToScale.
(a + b) print.
=> '1257.58'
shows the ''correct'' value in a table.

You can also use "<code>truncatedToScale</code>", to continue arithmetic with the truncated value.

== Fixed Decimals ==
(new with expecco 21.2) Similar to ScaledDecimals; however, these do '''NOT''' hold the correct result, but instead '''always round''' to the specified scale and thus the value used for further operations is the (rounded) value printed. 
Arithmetic operations will deliver a rounded result. Fixed decimals are good to represent money, especially when computing and printing sums of monetary values e.g. in an invoice.
 Example:
a := 1234.567 asFixedDecimal:2.
a print.
=> '1234.57'

b := 23.007 asFixedDecimal:2
b print.
=> '23.01'

(a + b) print.
=> '1257.58'
This looks correct to a human, as the values sum up correctly.

Be aware that converting a float to a FixedDecimal and back will not necessarily return the starting number. Unlike ScaledDecimals, FixedDecimals do NOT preserve the original value.

If you have a pre 21.2 version, the FixedDecimal behavior can be "simulated" by forcing a ScaledDecimal to round its value to the shown scale (as described above).

== Number Ranges ==
These behave like collections (see there) and are typically created by one of the following:
(''start'' '''to:''' ''stop'')
(''start'' '''to:''' ''stop'' '''by:''' ''step'')
For example:
(1 to:10) do:[:i |
Transcript showCR: e'{i} squared is {i squared}'.
]

== Complex Numbers ==
Are created as constants "<code>(''a'' + ''b'' i)</code>" or created with "<code>Complex real:''a'' imaginary:''b''</code>".
 An imaginary is created with the "<code>i</code>" message (e.g. "<code>5 i</code>" yields (0 + 5 i).
 Complex numbers print themself as "(''a'' + ''b'' i)".

Complex results can also be returned from e.g. the square root operator (sqrt) and logarithm operations (log, ln) IFF imaginary results are trapped (which means that an exception handler for the ImaginaryResult notification is present and proceeds the exception). The convenient helper "<CODE>trapImaginary:</CODE>" does that for you:
-4 sqrt
will report an error, whereas:
Number trapImaginary:[ -4 sqrt ]
will return a complex result (0+2.0i).

If imaginary results are not trapped, square root and log operators will signal an exception instead.

== Measurement Values ==
These hold an error percentage in addition to the actual value. These are useful to track upper and lower bounds of a measured or estimated value. Arithmetic operations will keep this error in the result.
 They can be constructed from any number via the "</CODE>±</CODE>" or "<CODE>±%</CODE>" binary operators:

:'''('''''aNumber'' '''±''' ''errRange''''')'''
:: a measurement value with ± an absolute error of ''errRange''.

:'''('''''aNumber'' '''±%''' ''percentage''''')'''
:: a measurement value with a relative error of ''percentage''.

For example,
 "<CODE>(50 ± 3)</CODE>" represents a measurement value with 6% accuracy (i.e. the actual value is somewhere in the interval [50-3 .. 50+3]),
and
 "<CODE>(100 ±% 3)</CODE>" represents a measurement value with 3% accuracy (i.e. the value is in [100-3 .. 100+3]).

Measurement values are not real numbers, but can in most operations be treated like one (i.e. the usual arithmetic operations are supported).

== Physical Values ==
These hold a number or measurement value in addition to a unit (e.g. meter, kilogram, volt, ampere, etc.). They are documented in depth in a [[PhysicalValues/en|separate part of this wiki]]. Physical values are created via unit operators ('meter', 'volt', 'ampere' etc.).

For example, "<CODE>50 volt</CODE>" represents a voltage value of 50 volts. Physical values are not numbers, but can in most parts be treated like one (i.e. most arithmetic operations are supported).
100 volt * 3
yields "300 V". And:
100 volt * 0.1 ampere
yields "10 W" (watt). And:
10 volt / 2 ampere
yields "5 ohm".

Physical values can also be combined with measurement values:
100 volt ±% 3
represents a measured voltage with 3% possible error (i.e. "(100 ± 3) V"). And:
10 volt ± 2 volt
represents a measured voltage with 20% error (i.e. value in [8 .. 12] V")

See details in the [[PhysicalValues/en|"Physical Values"]] document.

== Operations with Mixed Types ==

Normally, there is no need for explicit conversion between number types. The result of mixed operations is computed with the type of the operand which has the higher "''generality''". This conversion is called "''coercion''" - i.e. the operand with the lower generality is ''coerced'' into the type of the other before the operation is performed.

The order of generalities is:
Integer < Fraction < ScaledDecimal < FixedDecimal
< Float32 < Float64 < Float80 < Float128 < Float256 < LargeFloat < Complex
Thus, when a calculation involves both an integer and a fraction, the result will be a fraction (unless the result can be reduced to an integer).
 When an operation involves a float and an integer or fraction, the result will be a float.
 When either one is a complex, the result will also be.

When two floats are involved, the result will be generated with the higher precision.

==== Errors Propagate when Converting ====
But you should not be fooled by that: we do not get previously lost bits back, when a lower precision float is converted to a higher precision; the missing bits are simply assumed to be zero. In other words: "<CODE>ShortFloat pi asFloat</CODE>" will still only have roughly 7 digits of precision (which the original short float had), whereas "<CODE>Float pi</CODE>" will have its 15 digits.

This is a possible trap and a source for unexpected errors: be aware, that "0.1" (a double) is only an approximation to "0.1" (to about 15 digits).
I.e. this "0.1" has an error in the 1e-15 order, which "0.1" asFloat128 will also have.
 You cannot get a "0.1" with a smaller error from another float which already has this error.

Thus, either use "<code>0.1Q</code>" or "(<code>QuadFloat fromString:'0.1')</code>" or compute it with "<code>(1.0Q / 10.0Q)</code>", to get that 0.1 with 128bit precision.

==== Mixed Operations with MeasurementValues ====
Automatic conversion is also performed when MeasurementValues are involved:

:''aMeasurementValue'' '''+''' ''aNumber'' => MeasurementValue
:''aMeasurementValue'' '''-''' ''aNumber'' => MeasurementValue
::the result will have the same error as the receiver.
::E.g. (10 ± 1) + 10 => (20 ± 1).
 
:''aMeasurementValue'' '''*''' ''aNumber'' => MeasurementValue
:''aMeasurementValue'' '''/''' ''aNumber'' => MeasurementValue
::the error will also be scaled by ''aNumber''.
::E.g. (10 ± 1) * 10 => (100 ± 10).
 

==== Mixed Operations with PhysicalValues ====
PhysicalValues can be scaled by a scalar or multiplied by another physical value (possibly resulting in a value with a different unit). Addition and subtraction are only allowed if the arguments have the same base type:

:''aPhysicalValue'' '''+''' ''aNumber'' => error
:''aPhysicalValue'' '''-''' ''aNumber'' => error
::not allowed
 

:''aPhysicalValue'' '''*''' ''aNumber'' => PhysicalValue
:''aPhysicalValue'' '''/''' ''aNumber'' => PhysicalValue
::for example, <CODE>10 volt * 10</CODE> => <CODE>100 volt</CODE>,
::and <CODE>10 volt / 1000</CODE> => 10 milliVolt</CODE>
 

== Most Common/Useful Operations ==
=== Testing ===

:''aNumber'' '''isNaN''' => Boolean
:''aNumber''.'''isNaN'''() (in JS syntax)
::Check if number is NaN ("''Not a Number''"). Notice that there are multiple representations of "NaN": "<CODE>Float32 NaN</CODE>", "<CODE>Float64 NaN</CODE>" etc. Therefore, you should not compare against NaN with an identity compare operations (i.e. you should use isNaN to test, not compare for identity against another NaN)
 

:''aNumber'' '''isFinite''' => Boolean
::Check if number is not infinity and not NaN. As with NaN, there are multiple such "infinities"; one in each float class.
 

:''aNumber'' '''isInfinite''' => Boolean
::Check if number is either positive infinity (INF) or negative infinity (-INF).
 

:''aNumber'' '''isPositiveInfinity''' => Boolean
::Check if number is the positive infinity (+INF).
 

:''aNumber'' '''isNegativeInfinity''' => Boolean
::Check if number is the negative infinity (-INF).
 

:''aNumber'' '''isInteger''' => Boolean
::Check if number is an integral number.
 

:''aNumber'' '''isFraction''' => Boolean
::Check if number is a fractional number.
 

:''aNumber'' '''isFloat''' => Boolean
::Check if number is any float number (Float32, Float64, Float128, etc.).
 

:''aNumber'' '''exponent''' => Integer
::For floats only: returns the exponent, such that the number's value is: "mantissa * (2 ^ exponent)".
 

:''aNumber'' '''mantissa''' => Integer
::For floats only: returns the mantissa, such that the number's value is: "mantissa * (2 ^ exponent)".
 

:''aNumber'' '''precision''' => Integer
::For floats only: returns the number of bits in the number's mantissa.
 

:''aNumber'' '''decimalPrecision''' => Integer
::For floats only: returns the number of digits in the number's mantissa.
 

:''floatClass'' '''fmin''' => float
::For float classes only: returns the smallest representable (normalized) number of that class. For example, "<CODE>FloatD fmin</CODE>" would return 2.2250738585072e-308. Any operation which would generate a smaller number will deliver -INF.
 

:''floatClass'' '''fmax''' => float
::For float classes only: returns the largest representable number of that class. For example, "<CODE>FloatD fmax</CODE>" would return 1.79769313486232e+308. Any operation which would generate a larger number will deliver +INF.
 

:''floatClass'' '''emin''' / '''emax''' => integer
::For float classes only: returns the smallest and largest possible exponent representable by numbers of that class. For example, "<CODE>FloatD emin</CODE>" would return -1022. Notice that this is the exponent of the power-of-two; the corresponding decimal min/max exponent can be computed by multiplying it by log10(2).
 

:''aNumber'' '''isComplex''' => Boolean
::Check if number is a complex number.
 

:''aNumber'' '''negative''' => Boolean
::same as <code>''aNumber'' < 0</code>
 

:''aNumber'' '''positive''' => Boolean
::same as <code>''aNumber'' >= 0</code>
 

:''aNumber'' '''strictlyPositive''' => Boolean
::same as <code>''aNumber'' > 0</code>
 

:''anInteger'' '''isPrime''' => Boolean
::true if the number is a prime (integer) number
 

:''anInteger'' '''isPowerOf2''' => Boolean
::true if there exists an n, such that 2ˆn equals the number
 

:''anInteger'' '''isPowerOf:''' ''b'' => Boolean
::true if there exists an n, such that bˆn equals the number
 

=== Arithmetic ===

:''aNumber'' '''+''' ''aNumber'' => Number
:''aNumber'' '''-''' ''aNumber'' => Number
:''aNumber'' '''*''' ''aNumber'' => Number
:''aNumber'' '''/''' ''aNumber'' => Number
::The usual arithmetic operators. 
::All of the above allow operands of any number type, and will generate a result as appropriate. When dividing integers, an exact result is returned (either integer or fraction). If any of the arguments is inexact (i.e. a floating point number), the result will be inexact. If both are exact, the result will be exact. Fractional results are reduced to the greatest common divisor as denominator.
::[[Datei:point_right.png|20px]] Notice, that Smalltalk evaluates them left to right, without special precedences. Thus you should always use parentheses to group expressions when there are two or more operators in an arithmetic expression. It is good practice to use parentheses even in expressions where the evaluation order gives the correct result.
 

:''aNumber'' '''**''' ''aNumber'' => Number
:''aNumber'' '''raisedTo:''' ''aNumber'' => Number
::exponentiation (raising to a power)
::Examples:
<div style="margin-left: 2em;">
2 ** 20
=> 1048576
4 ** 3.5
=> 128.0
100 ** 0.5
=> 10.0
</div>
 

:''aNumber'' '''//''' ''aNumber'' => Integer
:''aNumber'' '''\\''' ''aNumber'' => Integer
::Truncated result and remainder (towards the next smaller integer i.e. towards negative infinity). The following equation holds: <code>(a // b) * b + (a \\ b) = a</code>
::Examples:
<div style="margin-left: 2em;">
100 // 3
=> 33
100 \\ 3
=> 1

-100 // 3
=> -34
-100 \\ 3
=> 2
</div>
 

:''aNumber'' '''quo:''' ''aNumber'' => Integer
:''aNumber'' '''rem:''' ''aNumber'' => Integer
::Truncated result (towards zero) and corresponding remainder. For positive arguments, this is the same as the above, for negative args, a different result is returned. However, the equation is similar to above: <code>(a quo: b) * b + (a rem: b) = a</code>
::Examples:
<div style="margin-left: 2em;">
100 quo: 3
=> 33
100 rem: 3
=> 1

-100 quo: 3
=> -33
-100 rem: 3
=> -1
</div>
 

:''aNumber'' '''abs''' => Number
::the absolute value.

:''aNumber'' '''negated''' => Number
::the negated value.

=== Mathematical and Trigonometric Functions ===
The usual operations are provided as unary messages to the number:

:''aNumber'' '''ln''' => Number
:''aNumber'' '''log10''' => Number
:''aNumber'' '''log2''' => Number
:''aNumber'' '''log:''' ''base'' => Number
:''aNumber'' '''integerLog10''' => Integer
:''aNumber'' '''integerLog2''' => Integer
::logarithm (natural, base10, base2 or arbitrary base).
::These are not restricted to floats; they can also be applied to big integers, as in: "<code>1000 factorial ln</code>".
::By default, an error is reported for negative numbers;
::to get a complex result, use "<code>Complex trapImaginary:[ aNumber ln ]</code>".
 

:''aNumber'' '''sqrt''' => Number
:''anInteger'' '''integerSqrt''' => Integer
::square root and truncated square root By default, an error is reported for negative numbers; to get a complex result, use "<code>Complex trapImaginary:[ aNumber sqrt ]</code>".
 

:''aNumber'' '''cbrt''' => Number
:''anInteger'' '''integerCbrt''' => Integer
::cubic root and truncated cubic root.
 

:''aNumber'' '''nthRoot:''' ''n'' => Number
::the nth root. "<code>n nthRoot:2</code>" gives the same result as "<code>sqrt</code>" and "<code>n nthRoot:3</code>" the same as the cubic root.
 

:''aNumber'' '''exp''' => Number
:''number1'' '''raisedTo:''' ''number2'' => Number
:''number1'' '''**''' ''number2'' => Number
::exponentiation; the "<code>**</code>" binary operator is an alias for "<code>raisedTo:</code>".
 

:''aNumber'' '''sin''' => Number
:''aNumber'' '''cos''' => Number
:''aNumber'' '''tan''' => Number
:''aNumber'' '''cot''' => Number (cotangent)
:''aNumber'' '''sec''' => Number (secant)
:''aNumber'' '''csc''' => Number (cosecant)
:''aNumber'' '''arcSin''' => Number
:''aNumber'' '''arcCos''' => Number
:''aNumber'' '''arcTan''' => Number
:''aNumber'' '''arcTan2:''' ''x'' => Number
::trigonometric functions
 

:''aNumber'' '''sinh''' => Number
:''aNumber'' '''cosh''' => Number
:''aNumber'' '''tanh''' => Number
:''aNumber'' '''arSinh''' => Number
:''aNumber'' '''arCosh''' => Number
:''aNumber'' '''arTanh''' => Number
::hyperbolic functions

=== Truncation and Rounding ===
:''aNumber'' '''ceiling''' => Number
::returns the next larger integer (unless aNumber is integral). E.g. truncates towards positive infinity.

:''aNumber'' '''floor''' => Number
::returns the next smaller integer (unless aNumber is integral). E.g. truncates towards negative infinity.

:''aNumber'' '''truncated''' => Integer
::truncates towards zero

:''aNumber'' '''truncateTo:''' ''grid'' => Number
::truncates towards the nearest multiple of ''grid''. E.g. "<code>1.284 truncateTo:0.1</code>" yields "1.2".

:''aNumber'' '''rounded''' => Number
::rounds up/down towards the nearest integer

:''aNumber'' '''roundTo:''' ''grid'' => Number
::rounds up/down towards the nearest multiple of ''grid''. E.g. "<code>1.284 roundTo:0.1</code>" yields "1.3" and "<code>523 roundTo:5</code>" yields "525".

:''aNumber'' '''roundToNumberOfDigits:''' ''n'' => Number
::rounds up/down for n valid digits. E.g. "<code>1.284 roundToNumberOfDigits:2</code>" yields "1.3" and "<code>5234 roundToNumberOfDigits:2</code>" yields "5200".

:''aNumber'' '''roundToPrecision:''' ''n'' => Number
::rounds up/down for n decimal fraction digits. E.g. "<code>1.284 roundToPrecision:2</code>" yields "1.28" and "<code>5234.356 roundToPrecision:2</code>" yields "5234.36".

=== Statistical / Combinatorical Functions ===

:''anInteger'' '''factorial''' => Integer
::the factorial; i.e. "<code>n factorial</code>" is 2*3*4...*n". Huge numbers are to be expected (try "<code>1000 factorial inspect</code>" in a workspace).

:''n'' '''binomialCoefficient:''' ''k'' => Integer
:''n'' '''binco:''' ''k'' => Integer
::the binomial coefficient (aka. ''n over k'' or the number of ways of picking k unordered outcomes from n possibilities)

:''n'' '''agm:''' ''y'' => Float
::the arithmetic-geometric mean

=== Other Special Functions ===

:''integer1'' '''gcd:''' ''integer2'' => Integer
::the greatest common divisor of integer1 and integer2.

:''integer1'' '''lcm:''' ''integer2'' => Integer
::the least common multiple of integer1 and integer2.

:''anInteger'' '''fib''' => Integer
::the nth Fibonacci number. Huge numbers are to be expected (try "<code>1000 fib inspect</code>" in a workspace).

:''aNumber'' '''fib_binet''' => Float
::an approximation of the nth Fibonacci number according to Binet. For example, "<code>5000 fib_binet</code>" gives: "1.0777734893072974780...e+10449" (by default with 200 bits precision)

:''aNumber'' '''erf''' => Float
::the error function

:''aNumber'' '''gamma''' => Float
::the gamma function

:''anInteger'' '''nextPrime''' => Integer
::the next prime number.

:''anInteger'' '''primeFactors''' => Collection
::the prime factors. Can take a long time for big numbers.

=== Bitwise Operators ===

:''integer1'' '''bitAnd:''' ''integer2'' => Integer
:''integer1'' '''bitOr:''' ''integer2'' => Integer
:''integer1'' '''bitXor:''' ''integer2'' => Integer
::bitwise and, or and exclusive or
:''integer1'' '''bitShift:''' ''count'' => Integer
::left shift if count is positive; right shift if negative
:''integer1'' '''leftShift:''' ''count'' => Integer
::left shift by count
:''integer1'' '''rightShift:''' ''count'' => Integer
::right shift by count
:''integer1'' '''bitTest:''' ''integer2'' => Boolean
::integer2 is used as a ''mask'' (i.e. bitTest returns true if any bit in the mask is set in the left operand i.e. (i1 & i2) not equal 0
:''integer1'' '''bitAt:''' ''bitNr'' => integer (0 or 1)
::extract the nth bit, with bitNr starting at 1
:''integer1'' '''lowBits:''' ''count'' => integer
::extract count lowest bits
:''integer'' '''highBit''' => integer (1..)
::the bit number of the highest bit, with bitNr starting at 1; zero if no bit is set
:''integer'' '''lowBit''' => integer (1..)
::the bit number of the lowest bit, with bitNr starting at 1; zero if no bit is set

=== Printing ===

Numbers can print themself on an output stream, or convert themself to a string:

:''aNumber'' '''printOn:''' ''aStream'' => void
:''aNumber'' '''printOn:''' ''aStream'' '''radix:''' ''base'' => void
:''aNumber'' '''printOn:''' ''aStream'' '''leftPaddedTo:''' ''length'' => void
:''aNumber'' '''printOn:''' ''aStream'' '''leftPaddedTo:''' ''length'' '''with:''' ''padCharacter'' => void
:''aNumber'' '''printOn:''' ''aStream'' '''paddedTo:''' ''length'' => void
:''aNumber'' '''printOn:''' ''aStream'' '''paddedTo:''' ''length'' '''with:''' ''padCharacter'' => void
:''aNumber'' '''printString''' => String
:''aNumber'' '''printStringRadix:''' ''base'' => String
:''aNumber'' '''printStringLeftPaddedTo:''' ''length'' => String
:''aNumber'' '''printStringLeftPaddedTo:''' ''length'' '''with:''' ''padCharacter'' => String
:''aNumber'' '''printStringPaddedTo:''' ''length'' => String
:''aNumber'' '''printStringPaddedTo:''' ''length'' '''with:''' ''padCharacter'' => String
::The above generate a standard format, which should fit most needs. The padded variants fill with either space or the explicit padCharacter. The printOn: variants will send the string to an output stream; the printString variants will return the string.
 

:''formatString'' '''printf:''' { ''arg''... } '''on:''' ''aStream'' => void
:''formatString'' '''printf:''' { ''arg''... } => String
::More fine control is available via the printf functions, which also offer a range of options to fill left or right, to control printing of the sign and to fill with zeros.
::These two interpret the receiver as a C-printf-style format string, and an argument vector as first argument (use a [[Smalltalk_Syntax_Cheat_Sheet#Expressions | brace-array constructor]] or pass a collection as argument). Thus, multiple values are printed as in the following example:
<div style="margin-left: 3em;">
'%04x %3d %+4.3f\n' printf:{ 123 . 4 . 3.14159 } on:Transcript
</div>
::Individual conversions (to a string) can also be done with:
<div style="margin-left: 3em;">
''aNumber'' '''printfPrintString:''' ''formatString'' => String
</div>
::Examples:
<div style="margin-left: 3em;">
'% .4f' printf:{Float pi} => ' 3.1416' (space after % ensures space for sign)
'% .4f' printf:{Float pi negated} => '-3.1416' (space after % ensures space for sign)
'%+.4f' printf:{Float pi} => '+3.1416' ('+' after % enforces sign)
'%+.4f' printf:{Float pi negated} => '-3.1416' ('+' after % enforces sign)
</div>
:: Please refer to a C-printf manual page (e.g. https://en.wikipedia.org/wiki/Printf_format_string).
:: Notice that printf accepts C-style character escapes (which is not the case in general with Smalltalk string constants)
 

:''aNumber'' '''printRomanOn:''' ''aStream'' => void
::roman style

=== Reading from Streams / Converting from Strings ===

Numbers can be read from a stream or converted from a string. There are slight differences between them:
* when reading from a stream of characters, the stream will be positioned after the number. So any non-digit character(s) after the number's characters will be returned by future read operations. The stream can be an internal or external (i.e. file-, pipe- or socket-) stream.
* when converting from a string, no extra characters are expected/allowed after the number's digits, except for whitespace. Thus you'll usually get an error when trying to convert a string with garbage characters after the number (which is not the case when reading from a stream).

Therefore, if you want to read a number from a string which may have garbage characters after the digits, you should first create a read-stream on the string, and then read the number from the stream (i.e. use "<code>Number readFrom:(''someString'' readStream)</code>" instead of "<code>Number fromString:''someString''</code>").

Numbers are read by sending the Number-class or one of its subclasses one of the "<code>readFrom:</code>" or "<code>fromString:</code>" messages.

If the class is the abstract class Number, then the read code will itself figure out, what kind of number to return. If the class is a concrete class (Float, Integer, Fraction etc.), you will get an instance of that class, unless the characters do not represent a valid number (of that class). In that case, an error is reported.

By default, errors are reported by raising an exception, unless you provide an error-handler as argument to the reader; more on that below.

:Number '''readFrom:''' ''aStream'' => someNumber or error
:: this can return an instance of any of the number types
:Number '''readFrom:''' ''aStream'' '''onError:'''[ ''errorValue'' ] => someNumber or errorValue
:: errorValue can be a constant, an arbitrary Smalltalk expression or even show a warn dialog or do whatever you like. In case of an error, the value returned from the read method will be the value provided by the error-block. Notice, that numbers themself respond to the <code>value</code> message and will return themself. Thus you can also provide a replacement value instead of an error block.
:Number '''fromString:''' ''aString'' => someNumber or error
:Number '''fromString:''' ''aString'' '''onError:'''[ ''errorValue'' ]</code> => someNumber or fallBackValue
:: similar, but does not allow for garbage characters after the number (except spaces)

:Integer '''readFrom:''' ''aStream''
:Integer '''readFrom:''' ''aStream'' '''onError:'''[...]
:Float '''readFrom:''' ''aStream''
:Float '''readFrom:''' ''aStream'' '''onError:'''[...]
:Integer '''fromString:''' ''aStream''
:Integer '''fromString:''' ''aStream'' '''onError:'''[...]
:Float '''fromString:''' ''aStream''
:Float '''fromString:''' ''aStream'' '''onError:'''[...]
:: similar to the above, but these will return a correspondingly typed number (i.e. an instance of Integer, Float, etc.

:''formatString'' '''sscanf:''' ''aString'' => collection
:: ''formatString'' is a printf/scanf-like format string; reads items from ''aString'' and returns a collection (i.e. an Array) of scanned objects. For example, <code> '%d %x %f' sscanf: '1234 FF 3.1415'</code> will return an array-like collection with 3 elements, the integer 1234, the integer 255 and the float 3.14159.

:''formatString'' '''scanf:''' ''aStream'' => collection
:: like above, but the elements will be read from a character stream

:To read binary numbers, refer to the stream API.

=== Conversion ===

In certain situations, it may be desirable to convert explicitly to a particular type, for example when binary data has to be verified or filled into a byte-buffer.

:''aNumber'' '''asInteger''' => Integer
::truncates to an integer (i.e. same as "truncated")

:''aNumber'' '''asFloat''' => Float64
:''aNumber'' '''asFloat64''' => Float64
:''aNumber'' '''asFloatD''' => Float64
::generates a double precision float; may generate +/- INF if the value cannot be represented as a double IEEE float (i.e. is out of range). asFloat64 and asFloatD are aliases for compatibility.
:''aNumber'' '''asFloatChecked''' => Float64 or error
::same as above, but reports an error if the value cannot be represented (instead of returning INF).

:''aNumber'' '''asShortFloat''' => Float32
:''aNumber'' '''asFloat32''' => Float32
:''aNumber'' '''asFloatE''' => Float32
::generates a single precision float; may generate +/- INF if the value cannot be represented as a single IEEE float. asFloat32 and asFloatE are aliases.
:''aNumber'' '''asShortFloatChecked''' => Float32 or error
::same as above, but reports an error if the value cannot be represented (instead of returning INF).
:''aNumber'' '''asLongFloat''' => Float80
:''aNumber'' '''asFloatQ''' => Float80
::generates an extended precision float; may generate +/- INF if the value cannot be represented as an extended IEEE float.
:''aNumber'' '''asLongFloatChecked''' => Float80 or error
::same as above, but reports an error if the value cannot be represented (instead of returning INF).
:''aNumber'' '''asQDouble''' => QDouble
::generates a qDouble
:''aNumber'' '''asQuadFloat''' => QuadFloat
:''aNumber'' '''asFloat128''' => QuadFloat
::generates a quadruple precision float (float128)
:''aNumber'' '''asOctaFloat''' => OctaFloat
:''aNumber'' '''asFloat256''' => QuadFloat
::generates an octuple precision float (float256)
:''aNumber'' '''asLargeFloatPrecision:''' ''numBits'' => LargeFloat
::generates an large float with numBits precision
:''aNumber'' '''asLargeFloatDecimalPrecision:''' ''numDigits'' => LargeFloat
::generates an large float with numDigits precision
:''aNumber'' '''asLargeFloat''' => LargeFloat
::generates an large float with the same precision as aNumber
:''aNumber'' '''asFraction''' => Fraction
::generates a fraction (from a float)
:''aNumber'' '''asScaledDecimal:''' ''scale'' => ScaledDecimal
::generates a scaled decimal which presents ''scale'' fractional digits
:''aNumber'' '''asFixedDecimal:''' ''scale'' => FixedDecimal
::generates a fixed decimal which rounds on and presents ''scale'' fractional digits
:''aNumber'' '''asComplex''' => Complex
::generates a complex (with 0 as imaginary part, same as "''nr'' + 0i")
:''aNumber'' '''i''' => Complex (that is a lower case i)
::generates a complex (with 0 as real part, e.g. as in "0 + ''nr'' i")

== Examples ==

==== Square root of 2 with different precision ====
nr := 2.0 sqrt.
'%.15g' printf:{nr}
=> '1.4142135623731'
'%.30g' printf:{nr}
=> '1.414213562373095101065700873732'
'%.50g' printf:{nr}
=> '1.41421356237309510106570087373256683349609375'
Be reminded that these floats (which are IEEE doubles) only provide 15 digits of accuracy ("Float decimalPrecision" returns 15). Thus the above attempts to generate more digits are useless and excess digits are more or less random.

More valid digits are returned by QDoubles ("QDouble decimalPrecision" returns 61):
nr := 2.0 asQDouble sqrt.
'%.30g' printf:{nr}
=> '1.41421356237309504880168872421'
'%.50g' printf:{nr}
=> '1.4142135623730950488016887242096980785696718753769'
'%.100g' printf:{nr}
=> '1.414213562373095048801688724209698078569671875376948073176679737988424424484343089516915416653038211'
Here again, digits after the 60th are wrong.

With octuple precision floats ("OctaFloat decimalPrecision" returns 71) we get:
nr := 2.0 asOctaFloat sqrt.
'%.30g' printf:{nr}
=> '1.41421356237309504880168872421' (a quadruple precision float)
'%.50g' printf:{nr}
=> '1.4142135623730950488016887242096980785696718753769'
'%.100g' printf:{nr}
=> '1.41421356237309504880168872420969807856967187537694807317667973799073247801160833747418698891953623'

Finally, an arbitrary number of digits can be computed with LargeFloats (here we use a precision of 1000 bits for roughly 300 digits):
nr := (2.0 asLargeFloatPrecision:1000) sqrt.
'%.30g' printf:{nr}
=> '1.41421356237309504880168872421'
'%.50g' printf:{nr}
=> '1.4142135623730950488016887242096980785696718753769'
'%.100g' printf:{nr}
=> '1.414213562373095048801688724209698078569671875376948073176679737990732478462107038850387534327641573'

In most situations, double precision is sufficient. However, some computations generate intermediate results which are outside the precision or range of IEEE doubles. See "[[Do not trust Floating Point]]" for a classic (surprising) example.

==== Reading Numbers ====

readFrom: will not accept garbage characters after the number iff the argument is a string:
in := '123.456abc'.
Number readFrom: in.
=> error due to garbage after number ('abc')

However, it behaves different, if the argument is a stream. Then the stream will be left positioned after the number's string:
Number readFrom: (in readstream).
=> 123.456
(stream will be left positioned at the 'abc')

here, reading the rest after the number's digits:
s := in readstream.
val := Number readFrom: s.
rest := s upToEnd.
=> val: 123.456
rest: 'abc'

you can provide an error-value:
val := Number readFrom:'bla' onError:[0]
=> val: 0

or perform any action inside the onError arg block:
val := Number readFrom:'blabla' onError:[ Dialog warn:'bad input'. nil ]
=> (Dialog shown)
val: nil

an alternative to "readFrom:" is scanf, which can also read multiple values from a stream:
row := '%d %f %s' scanf:(ReadStream on:'1234 1111.2345 Fritz').
=> OrderedCollection(1234 1111.2345 'Fritz')
i.e. an integer, a float and a string

or from a string:
myString := '1234 1111.2345 Fritz'.
row := '%d %f %s' scanf: myString.
=> OrderedCollection(1234 1111.2345 'Fritz')
i.e. same as above

scanf can also be used to extract numbers which are not delimited by spaces (you have to specify the field length in the format):
myString := '1.234.5679875679'.
'%4f %5f %3d %4d' scanf:myString
=> OrderedCollection(1.23 4.567 987 5679)

== Printf Format Specifier ==

Characters not escaped by a '%' are printed as-is.
Following a '%' there can be:
* optional: '-' (POSIX refers to this as the <<flags>>)
* optional: positive number or '*' (POSIX: <<width>>)
* optional: period followed by positive number or * (POSIX: <<precision>>)
* optional: an h or l to indicate size of data (POSIX: <<length>>)
* required: character describing output behavior (POSIX: <<conversion specifier>>)

The format follows the ''official'' C-library printf formats; however, there are differences in
the various printf implementations:

ANSI standards up through C99:
* more flags: '+' ' ' '0' '#'
* more lengths: 'L' 'hh' 'll' 'j' 'z' 't'
* more conversions: 'F' 'a' 'A' 'n'

The POSIX specification of printf added:
* positional parameters to identify argument indices
* more flags: ''' (single quote)
* more conversions: 'C' 'S'
* clarifications regarding corner cases and 'undefined behavior'

BSD implementations added:
* more lengths: 'q'
* more conversions: 'D' 'U' 'O'

glibc (GNU) added:
* more lengths: 'Z'
* more conversions: 'm'

Windows C Runtime (CRT) added:
* more lengths: 'I' 'I32' 'I64' 'w'

glibc and CRT both added length 'Z'.
* glibc uses 'Z' for the length size_t.
* CRT uses Z as a conversion for length-prefixed strings.

The expecco/Smalltalk implementation handles 'Z' in the same way as 'z'.

BSD and IBM C library both added 'D'.
* BSD uses D as a conversion, namely as an alias of 'ld'.
* IBM uses 'D' for the length for _Decimal64, a decimal floating point type,
* in accordance with ISO/IEC TR 24732.
The Smalltalk implementation takes the former approach.

The expecco/Smalltalkimplementation also adds new conversions:

* 'b' and 'B' for binary (base-2) integer renderings
* 'y' and 'Y' for true/false and yes/no Boolean conversions
* 'J' for JSON (assuming that the object can be JSON-encoded)
* 'T' and 'V' for JS typeof and valueOf inspection
* 'S' for store-string (of any object)
* 'P' for print-string (of any object)

Prefixes:
* ' ' fill with spaces
* '0' fill with zeros
* '+' print the sign
* '-' left justified
* '#' depends:
** %o, %x, %b: print base prefix
** %e always show decimal point
** %e, %E, %f, %g always show decimal point

Conversions:
* 'a' (not implemented) hex floating point exp form
* 'b' binary (base 2)
* 'c' character or (first char of string)
* 'd' integer
* 'e' base-10 floating point exp form (scientific)
* 'f' base-10 floating point decimal form (non-scientific)
* 'g' 'e' or 'f', whichever looks more appropriate (based on the float-value)
* 'i' integer (alias for 'd')
* 'j' (not implemented) use 'J' for JSON format
* 'n' (not implemented) stores number of characters written so far into arg
* 'o' base-8 octal
* 'p' (not implemented) pointer
* 's' string
* 't' type (i.e. class name)
* 'u' (not implemented) unsigned (negative values are converted)
* 'v' (not implemented) store string
* 'x' base-16 hex
* 'X' base-16 hex upper case

Parameter selection (not implemented):
* <n>$ take n'th parameter

Dynamic width/precision (consumed in order as presented):
* "*" take width/parameter from next argument

Special output specifier:
* <n>! if the number's string is larger than the field width <n>, it will be filled with '#'s. Useful if you want to ensure tabular data to remain aligned. This is not a posix printf specified, but a Smalltalk/X extension.

Examples 1):
'|%d|' printf: { 123 } -> '|123|'
'|%5d|' printf: { 123 } -> '| 123|'
'|%-5d|' printf: { 123 } -> '|123 |'

'|%s|' printf: { 'abc' } -> '|abc|'
'|%5s|' printf: { 'abc' } -> '| abc|'
'|%*s|' printf: { 5 . 'abc' } -> '| abc|'

'|%f|' printf: { 1.234 } -> '|1.234|'
'|%#f|' printf: { 1.234 } -> '|1.234000|'

'|%8f|' printf: { 1.234 } -> '| 1.234|'
'|%*f|' printf: { 8 . 1.234 } -> '| 1.234|'
'|%10f|' printf: { 1.234 } -> '| 1.234|'
'|%#10f|' printf: { 1.234 } -> '| 1.234000|'

Negative width will fill at the right:
'|%5s|' printf: { 'abc' } -> '| abc|'
'|%-5s|' printf: { 'abc' } -> '|abc |'
'|%-*s|' printf: { 5 . 'abc' } -> '|abc |'
'|%*s|' printf: { -5 . 'abc' } -> '|abc |'

'|%-8f|' printf: { 1.234 } -> '|1.234 |'
'|%*f|' printf: { -8 . 1.234 } -> '|1.234 |'
'|%-*f|' printf: { 8 . 1.234 } -> '|1.234 |'
'|%-*f|' printf: { -8 . 1.234 } -> '|1.234 |'

A Zero as fill character (only at the left):
'|%05s|' printf: { 'abc' } -> '|00abc|'
'|%05d|' printf: { 123 } -> '|00123|'

Field width overflow:
'|%4d|' printf: { 123456 } -> '|123456|'
'|%4!d|' printf: { 123456 } -> '|####|'

The case (upper vs. lower) of the float-format character affects printing of Nan, Infinity and exponent separator:
'%f' printf: { 1.234 } -> '1.234000'
'%F' printf: { 1.234 } -> '1.234000'
'%e' printf: { 1.234 } -> '1.234e0'
'%E' printf: { 1.234 } -> '1.234E0'
'%f' printf: {Float NaN} -> 'nan'
'%F' printf: {Float NaN} -> 'NAN'
'%f' printf: {Float infinity} -> 'inf'
'%F' printf: {Float infinity} -> 'INF'
'%f' printf: {Float negativeInfinity} -> '-inf'
'%F' printf: {Float negativeInfinity} -> '-INF'
'%-F' printf: {Float infinity} -> '+INF'
'%-F' printf: {Float negativeInfinity} -> '-INF'
'% F' printf: {Float infinity} -> ' INF'
'% F' printf: {Float negativeInfinity} -> '-INF'

1) Reminder: the "{ ... }" syntax in Smalltalk generates an Array containing the elements (expressions) separated by periods. I.e. "{ 1+2 . 3+4 }" would generate an array with 2 elements: 3 and 7. With constant arguments, this is (almost) equivalent to #( el1 el2) (without periods). Except for the fact, that constant arrays are immutable (readonly), whereas the brace construct instantiates a new array which is mutable.

== Scanf Format Specifier ==

The Smalltalk implementation adds new conversions:

Conversions (upper case same as lower case):
* 'b' binary (base 2)
* 'c' character or (first char of string)
* 'd' decimal
* 'e' float
* 'f' float
* 'g' float
* 'i' integer (alias for 'd')
* 'o' base-8 octal
* 's' string
* 'u' integer
* 'x' base-16 hex
* 'n' any number
* 'J' JSON object (upper case 'J' only)

Length prefix:

* 'h' with float formats: reads as ShortFloat
* 'L' with float formats: reads as LongFloat

Examples:
'%d %x' sscanf:'1234 ff00' -> OrderedCollection(1234 65280)
'%d %s' sscanf:'1234 ff00' -> OrderedCollection(1234 'ff00')
'%d %x %b' sscanf:'1234 ff00 1001' -> OrderedCollection(1234 65280 9)

('%f' sscanf:'1234') first -> 1234.0 (Float i.e. an IEEE double)
('%lf' sscanf:'1234') first -> 1234.0 (Float i.e. an IEEE double)
('%llf' sscanf:'1234') first -> 1234.0 (Float i.e. an IEEE double)

('%hf' sscanf:'1234') first -> 1234.0 (ShortFloat i.e. an IEEE single)
('%Lf' sscanf:'1234') first -> 1234.0 (LongFloat i.e. an IEEE extended)
('%LLf' sscanf:'1234') first -> 1234.0 (QDouble)

= See Also =

[[Numeric Limits/en|Numeric Limits]] provides additional info on precision, ranges and problems with floating point numbers.

String API Functions

2026-02-23T10:46:54Z

Sv: Änderung übernommen aus altem Wiki von cg, 16.2.26

This document lists most useful (and most often needed) string functions.
Be aware, that there are many more to be found in either the class references or via the builtin [[Tools_ClassBrowser/en | class browser]].

See also [[Expecco_API/en#String_Handling | "String Handling"]] in [[Expecco_API]].
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,String String]
inherits from: [http://live.exept.de/ClassDoc/classDocOf:,CharacterArray CharacterArray]
[http://live.exept.de/ClassDoc/classDocOf:,Collection Collection]

[[Useful API Functions | Back to Useful API Functions]]

[[Datei:point_right.png|20px]] Notice: unless written otherwise, all indices are 1-based. Valid indices range from 1 to the string's size.

== Literals (i.e. Constant Strings) ==

Literals are constants in the source code or in expressions entered into a workspace for immediate execution.
Literal objects are created at compile time and are immutable. That means that an exception will be raised, if the program tries to modify the contents of a literal string at execution time.

Tradititionally, Smalltalk supported only one type of literal string constant,
which does not support special character escapes (i.e. it was consequently following the philosophy of "''no surprises''" and "''what you see is exacty what you get''"). This has some charm and might be easier to understand for beginners, but makes life of programmers hard at times (think of newlines or tab characters inside a string).
 
For this reason, the underlying Smalltalk/X has been extended to support C-like escaped strings, strings with embedded expressions and international strings which are automatically translated to a national language. Syntaxwise, extended string literals have a prefix such as 'c', 'e' or 'i'.

Notice that the Python language provides aimilar mechanisms, but has the C-style as default, and the untranslated literal as so-called "''raw''" string literal prefixed by an 'r'.

===== Traditional String Literals (''what you see is what you get'') =====
:'...'
::Smalltalk style string (as is; no escapes for special characters). Be aware, that this is inconvenient, if newlines, tabs or other non-graphical characters are to be in the string. Notice that Smalltalk's plain strings are similar to Python's "''Raw Strings''".

===== C-Style String Literals (with C escapes) =====
:c'...'
::C style string (supports the usual C-escapes, such as "\n" for newline, "\t" for tab or "\xHH" and "\uHHHH" for hex codes). Backslashes and single quotes must be prefixed by a backslash (which is especially needed when a string represents a Windows pathname). For example, the literal <code>c'abc\u2021def'</code> represents the characters "abc‡def".

===== Expression Strings (with sliced in expressions) =====

:e'...{expr}...'
:: C style with embedded expressions. In addition to C-style escapes, expressions in braces are embedded. These expressions are evaluated (at execution time) and their string representation (i.e. the ''printString'', which is Smalltalk's equivalent of ''toString'' in JS) sliced into the string. Example:
<div style="margin-left: 2em;">
a := 1234.
b := true.
c := 'hello'.
foo := e'{c}; this string contains embedded exprs.\nYes, {b} and {a} are there.'
foo
=> 'hello; this string contains embedded exprs.
Yes, true and 1234 are there.'
</div>
::Strictly speaking, these are not literals. Instead, the Smalltalk compiler generates code which expands these at execution time.
::Semantically, they are equal to a "bindWith:" message (see String class), sent to a string with "%" markers.
::(Don't care, if that is too technical).

===== National Language Strings =====
:i'...{expr}...'
:: C style with embedded expressions and automatic nationalization. First, it is expanded as a C-style string. Then a translation is looked up in the currently loaded language resources. The template searched has successive expression positions replaced by "%i".
::For example, the literal "<code>i'Hello {name}'</code>" will look for a translation of "Hello %1" in the language pack, and may find one of "Hallo %1", "Hola %1", etc. depending on your current language setting. Then the variable "name" is converted to a string and sliced in, finally generating "Hallo Tom" or "Hola Tom" etc.
::Translations are loaded from resource files in the "resources" folder.

===== Regex Literals =====
:r'...'
:: these are implemented, but not yet officially released to the public. Don't use for now, instead use the normal regex messages as described below.

== Protocol (String API) ==

String provides a huge amount of functionality, both in the String class itself and also due to inheritance from a number of Collection classes (be reminded that a string is a sequencable collection of characters, therefore all of the API implemented in collections which support an integer index and those implemented for any generic collection is also provided. Worth mentioning are the enumeration methods, the search, and the substring methods).
Use a SystemBrowser and/or the MethodFinder to get a feeling. There is usually an existingsolution for most needs.

=== Queries ===

:''aString'' '''size'''
:''aString'''''.size()''' [JS]
::Returns the number of characters in the string (i.e. the string's length).
::Example:
<div style="margin-left: 4em;">
'hello world' size</code>
=> 11
</div>

:''aString'' '''bitsPerCharacter'''
::Returns one of {8, 16, 32}.

:''aString'' '''isWideString'''
::Same as "<code>aString bitsPerCharacter > 8</code>"

:''aString'' '''containsNon7BitAscii''''
::true if aString is either a wide string, or contains any character above the 7bit Ascii range (i.e. a national character in the ISO8859 charset)

=== Accessing ===

The general access methods for any collection in Smalltalk are "<CODE>at:</CODE>''index''" and "<CODE>at:</CODE>''index'' <CODE>put:</CODE>''anObject''" (i.e. the at: and at:put: messages).
 However, for your convenience, the Smalltalk compiler also supports square brackets as used in most other languages.
Semantically, these are the same, as the compiler generates the corresponding accessor calls for bracket indexes.

:''aString'' '''at:''' ''index''
:''aString''' ''[''' ''índex'' ''']'''   [ST/X]1
:''aString''' ''[''' ''índex'' ''']'''   [JS]
::Returns the character at an index (1-based; valid indices are [1 .. size]).
::Example:
<div style="margin-left: 4em;">
'hello world' at:2
=> $e
</div>

:''aString'' '''at:''' ''index'' '''put:''' ''char''
:''aString''' ''[''' ''índex'' ''']''' := ''char''   [ST/X]1
:''aString''' ''[''' ''índex'' ''']''' = ''char''   [JS]
::Changes the character at an index (1-based; valid indices are [1 .. size]). Notice that string constants (and freeze values) are immutable (i.e. readonly strings). Only strings which have been created dynamically can be modified.

:1) this non-ANSI-Smalltalk syntax is supported by Smalltalk/X and thus also valid in expecco.

=== Copying ===
:''aString'' '''copy'''
::Generates a mutable copy.
::Example:
<div style="margin-left: 4em;">
'hello world' copy at:1
=> $h
</div>

:''aString'' '''copyFrom:''' ''startIndex'' '''to:''' ''endIndex''
:''aString'''''.copyFrom_to(''' ''startIndex'', ''endIndex'' ''')'''   [JS]
::Copies characters from a start index to an end index (1-based; valid indices are [1 .. size]).
::Example:
<div style="margin-left: 4em;">
'hello world' copyFrom:1 to:5.
=> 'hello'
</div>
:''aString'' '''copyFrom:''' ''startIndex'' '''count:''' ''numChars''
:''aString'''''.copyFrom_count(''' ''startIndex'', ''numChars'' ''')'''   [JS]
::Copies a number of characters starting at the given index.
::Example:
<div style="margin-left: 4em;">
'hello world' copyFrom:7 count:3.
=> 'wor'
</div>
:''aString'' '''copyFrom:''' ''startIndex''
:''aString'''''.copyFrom(''' ''startIndex'' ''')'''   [JS]
::Copies from the given index to the end.
::Example:
<div style="margin-left: 4em;">
'hello world' copyFrom:6.
=> ' world'
</div>
:''aString'' '''copyTo:''' ''endIndex''
:''aString'''''.copyTo(''' ''endIndex'' ''')'''   [JS]
::Copies from the start to the given index.
::Example:
<div style="margin-left: 4em;">
'hello world' copyTo:6.
=> 'hello '
</div>
:''aString'' '''copyLast:''' ''count''
:''aString<'''.copyLast(''' ''count'' ''')'''   [JS]
::Copies the last count characters.
::Example:
<div style="margin-left: 4em;">
'hello world' copyLast:4.
=> 'world '
</div>
:''aString'' '''copyButFirst:''' ''count''
:''aString'''''.copyButFirst(''' ''count'' ''')'''   [JS]
::Copies except for the first count characters.
::Example:
<div style="margin-left: 4em;">
'hello world' copyButFirst:4.
=> 'o world'
</div>
:''aString'' '''copyButLast:''' ''count''
:''aString'''''.copyButLast(''' ''count'' ''')'''   [JS]
::Copies except for the last count characters.
::Example:
<div style="margin-left: 4em;">
'hello world' copyButLast:4.
=> 'hello w'
</div>
:''aString'' '''copyBetween:''' ''leftString'' '''and:''' ''rightString'' '''caseSensitive:''' ''boolean''
:''aString'''''.copyBetween_and_caseSensitive(''' ''leftString'', ''rightString'', ''boolean'' ''')'''   [JS]
::Finds two substrings and copies the part between them.
::Example:
<div style="margin-left: 4em;">
'hello small world' copyBetween:'hello' and:'world' caseSensitive:true
=> ' small '

'helloworld' copyBetween:'hello' and:'world' caseSensitive:true
=> '' (an empty string)

'hello small World' copyBetween:'hello' and:'world' caseSensitive:true
=> nil

'hello small World' copyBetween:'hello' and:'world' caseSensitive:false
=> ' small '
</div>
:''aString'' '''copyReplaceString:''' ''oldString'' '''withString:''' ''newString''
:''aString'''''.copyReplaceString_withString(''' ''oldString'', ''newString'' ''')'''   [JS]
::Example:
<div style="margin-left: 4em;">
'hello small world' copyReplaceString:'small' withString:'big'
=> ' hello big world '

'hello small world' copyReplaceString:'big' withString:'bigger'
=> ' hello small world '
</div>
:''aString'' '''withoutPrefix:''' ''prefixString'' [ '''caseSensitive:''' ''boolean'' ]
:''aString'''''.withoutPrefix[_caseSensitive](''' ''prefixString'' [, ''boolean'' ]''')'''   [JS]
::If string starts with a prefix-string, return a copy without it. Otherwise return the original string.
::Example:
<div style="margin-left: 4em;">
'hello small world' withoutPrefix:'hello '
=> ' small world '

'small world' withoutPrefix:'hello '
=> ' small world '
</div>
:''aString'' '''withoutSuffix:''' ''suffixString'' [ '''caseSensitive:''' ''boolean' ]'
:''aString'''''.withoutSuffix[_ caseSensitive](''' ''suffixString'' [, ''boolean'' ''')'''   [JS]
::If string ends with a prefix-string, return a copy without it. Otherwise return the original string.
::Example:
<div style="margin-left: 4em;">
'hello small world' withoutSuffix:' world'
=> ' hello small'

'hello small' withoutSuffix:' world'
=> ' hello small '
</div>

=== Concatenation ===

:''string1'' <code>,</code> ''string2''
:''string1'' <code>+</code> ''string2'' [JS]
::the Smalltalk comma operator1 and the JavaScript plus operator concatenate two strings
::Example (Smalltalk):
<div style="margin-left: 4em;">
'hello' , ' ' , 'world'
=> 'hello world'
</div>
::Example (JavaScript):
<div style="margin-left: 4em;">
"hello" + " " + "world"
=> "hello world"
</div>

:''string'' <code>,*</code> ''integer''
::the Smalltalk comma-star operator generates a new string by repeating the first string a number of times
::Example:
<div style="margin-left: 4em;">
'abc' ,* 5
=> 'abcabcabcabcabc'
</div>

1)Although in theory, the plus operator could have been overloaded in Smalltalk as well, this was not done for readability and debuggability reasons: using a comma makes it clear that the intention is string concatenation and not addition.
Also notice, that the JavaScript semantics can be considered unclean, as it concatenates strings if either operand is a string. Thus, you have to be careful if addition is attempted, and either incoming operand could possibly be a string.
 In contrast, Smalltalk will report an error if you try to concatenate or add strings and numbers.
 it is not inconvenience - its a feature to protect you from stupid and hard to find errors!

=== Splitting ===

:''aString'' '''splitBy:''' ''aCharacter''
:''aString'''''.splitBy(''' ''aCharacter'' ''')''' [JS]
::Splits a string into pieces, given a splitting character. The result is a collection containing the parts. 
::Examples:
<div style="margin-left: 4em;">
'hello world here are six words' splitBy: $ <- trailing invisible space here
=> #( 'hello' 'world' 'here' 'are' 'six' 'words')

'hello world here are six words' splitBy: (Character space) <- no invisible space
=> #( 'hello' 'world' 'here' 'are' 'six' 'words')

'hello-world here are six-words' splitBy: $-
=> #( 'hello' 'world here are six' 'words')
</div>
:''aString'' '''splitOn:''' ''aCharacter''
:''string1'' '''splitOn:''' ''string2''
:''string1'' '''splitOn:''' ''regex''
:''aString'' '''splitOn:''' '''[''':''char'' '''|''' ''<condition-expression on char>'' ''']'''
:''aString'' '''splitOn:''' #''<name of condition-expression on char>''
:''aString'''''.splitOn(''' ''aCharacter'' ''')'''   [JS]
:''string1'''''.splitOn(''' ''string2'' ''')'''   [JS]
:''aString'''''.splitOn(''' (''char'') => ''<condition-expression on char>'' ''')'''   [JS]
::Splits a string into pieces, given a splitter. The splitter may be a single character, a string, a regular expression or a block/the name of an element-method, which returns true to split. This is a more general version of the above "splitBy:", for complex splits.
::Examples:
<div style="margin-left: 4em;">
'hello here are five words' splitOn: $ <- trailing space here
=> #( 'hello' 'here' 'are' 'five' 'words')

'hello here are five words' splitOn:(Character space) <- the same, but readable
=> #( 'hello' 'here' 'are' 'five' 'words')

'hello-world here are six-words' splitOn: $-
=> #( 'hello' 'world here are six' 'words')

'hello world and goodbye world' splitOn: ' and '
=> #( 'hello world' 'goodbye world')

'hello, commas and semis; here' splitOn: [:ch | (ch == $,) or:[ ch == $; ]]
=> #( 'hello' 'commas and semis' 'here')

'hello, commas and semis; here' splitOn: [:ch | ',;' includes:ch ]] <- same functionality as above
=> #( 'hello' 'commas and semis' 'here')

'aWordWithCamelCase' splitOn: [:ch | ch isUppercase ]
=> #( 'a' 'Word' 'With' 'Camel' 'Case')

'aWordWithCamelCase' splitOn: #isUppercase
=> #( 'a' 'Word' 'With' 'Camel' 'Case')

c'some text\twith\ndifferent separators' splitOn: #isSeparator
=> #( 'some' 'text' 'with' 'different' 'separators')

'123abc456def789' splitOn:'[a-z]*' asRegex
=> #('123' '456' '789')

JS examples:
"hello here are five words".splitOn( $' ' ) <- space character here
=> [ "hello" , "here" , "are" , "five" , "words" ]

"hello here are five words".splitOn( ' ' ) <- string with a space here
=> [ "hello" , "here" , "are" , "five" , "words" ]

"hello world and goodbye world".splitOn(" and ")
=> [ "hello world" , "goodbye world"]

"123abc456def789".splitOn("[a-z]*" asRegex)
=> [ "123" "456" "789" ]

"hello-world, commas and semis; here".splitOn( (ch) => (ch == $',') || ( ch == $';') )
=> [ "hello-world" , "çommas and semis" , "here"]
</div>

=== Case Conversion ===

:''aString'' '''asLowercase'''
:''aString'' '''asUppercase'''
:''aString'' '''asUppercaseFirst'''
:''aString'''''.asUppercase()'''   [JS]
:''aString'''''.asLowercase()'''   [JS]
:''aString'''''.asUppercaseFirst()'''   [JS]
::Covert to lowercase, uppercase
::Example:
<div style="margin-left: 4em;">
'HELLO' asLowercase
=> 'hello'

'hello' asUppercase
=> 'HELLO'

'hello' asUppercaseFirst
=> 'Hello'
</div>

::Be aware that these functions do not care for some special cases in the Unicode character set, where a single character has to be replaced by two characters or by a different character depending on the position (and most, even native programmers do not know about them!).
::The german "ß" (usually up-cased as "SS") is one example of the first kind, the greek sigma which has to be down-cased differently depending on its position within a string is one of the second kind.
::
::If your test depends on such specifics, it must handle that itself (the 2008 Unicode standard does however include an upper-case eszet, which is handled by those functions).

=== Comparing ===

Be reminded that there are multiple possible definitions of "''being equal''" w.r.t. strings; identity, equality and case-insensitive equalitiy.
 Identity is about two objects being the identical object (instance), and handled by the "==" operator in Smalltalk.
 Equality means being of the same type of object and having the same contents is handled by the "=" operator.

:''string1'' '''= ''' ''string2''
:''string1'''''== ''' ''string2''   [JS]
::Compares two strings for equal contents, NOT ignoring case. Notice that "==" in Smalltalk is an identity compare, which is "===" in JavaScript, and "=" in Smalltalk is a "same contents" compare, whereas its assignment in JS. Keep that in mind to avoid hard to find bugs.

::Example:
<div style="margin-left: 4em;">
'HELLO' = 'HeLlo'
=> false

'hello' = 'hello' copy
=> true

'hello' == 'hello' copy
=> false

'hello' = 'hello' asUnicode16String
=> true
</div>

:''string1'' '''sameAs:''' ''string2''
:''string1'''''.sameAs(''' ''string2'' ''')'''   [JS]
::Compares two strings, ignoring case. "'''caselessEqual:'''" is an alias which performs the same operation (and may be more self describing).

::Example:
<div style="margin-left: 4em;">
'HELLO' sameAs: 'HeLlo'
=> true

'HELxO' sameAs: 'HeLlo'
=> false

'HELLO' caselessEqual: 'HeLlo'
=> true
</div>

:''string1'' '''caselessBefore:''' ''string2''
:''string1'' '''caselessAfter:''' ''string2''
:''string1'' '''caselessEqual:''' ''string2''
:''string1'''''.caselessBefore(''' ''string2'' ''')'''   [JS]
:''string1'''''.caselessAfter(''' ''string2'' ''')'''   [JS]
::Compare two strings, ignoring case. Returns true if string1 is smaller, same or larger than string2. Does not care for national characters (i.e. the compare is based on the unicode points)

::Example:
<div style="margin-left: 4em;">
'HELLO' caselessBefore: 'world'
=> true

'bce' caselessBefore: 'abc'
=> false
</div>

:''string1'' '''startsWith:''' ''prefixString''
:''string1'' '''startsWith:''' ''prefixString'' '''caseSensitive:''' ''boolean''
:''string1'''''.startsWith(''' ''prefixString'' ''')'''   [JS]
:''string1'''''.startsWith_caseSensitive(''' ''prefixString'', ''boolean'' ''')'''   [JS]
::Checks if a string starts with another string.
::Comes in two variants, one being strict, the other with optional case-insensitivity.
::Example:
<div style="margin-left: 4em;">
'hello' startsWith: 'hel'
=> true

'Hello' startsWith: 'hel'
=> false

'Hello' startsWith: 'hel' caseSensitive: false
=> true

'Hexlo' startsWith: 'hel' caseSensitive: false
=> false
</div>

:''string1'' '''endsWith:''' ''prefixString''
:''string1'' '''endsWith:''' ''prefixString'' '''caseSensitive:''' ''boolean''
::Checks if a string ends with another string. Comes in two variants, one being strict, the other with optional case-insensitivity.
::Example:
<div style="margin-left: 4em;">
'hello' endsWith: 'lo'
=> true

'Hello' endsWith: 'Lo'
=> false

'Hello' endsWith: 'Lo' caseSensitive: false
=> true

'Hexlo' endsWith: 'LX' caseSensitive: false
=> false
</div>

=== Searching ===

:''aString'' '''indexOf:''' ''aCharacter''
:''aString'' '''lastIndexOf:''' ''aCharacter''
::Returns the first/last index of an element (a character). The index is 1-based; returns 0 if not found.
::Example:
<div style="margin-left: 4em;">
'HELLO' indexOf: $L
=> 3

'HELLO' indexOf: $x
=> 0

'HELLO' lastIndexOf: $L
=> 4
</div>
:''aString'' '''indexOf:''' ''aCharacter'' '''startingAt:''' ''startIndex''
:''aString'' '''lastIndexOf:''' ''aCharacter'' '''startingAt:''' ''startIndex''
::Returns the next/previous index of an element (a character) given a search start index . Returns 0 if not found.
::Example:
<div style="margin-left: 4em;">
'HELLO WORLD' indexOf: $O startingAt: 6
=> 8

'HELLO WORLD' indexOf: $x startingAt: 6
=> 0

'HELLO WORLD' indexOf: $L startingAt: 6
=> 0

'HELLO WORLD' lastIndexOf: $O startingAt: 7
=> 5
</div>

:''aString'' '''indexOfAny:''' ''aCollectionOfCharacters'' [ '''startingAt:''' ''startIndex'' ]
:''aString'' '''lastIndexOfAny:''' ''aCollectionOfCharacters'' [ '''startingAt:''' ''startIndex'' ]
::Similar to the above, but searches for any element in the given argument collection. This may be a string (of characters) or an array or any other collection of characters. Returns 0 if not found.
::Example:
<div style="margin-left: 4em;">
'HELLO, WORLD' indexOfAny: ',;'
=> 6

'HELLO; WORLD' indexOfAny: ',;'
=> 6

'HELLO; WORLD' indexOfAny: #( $, $; )
=> 6

'HELLO. WORLD' indexOfAny: #( $, $; )
=> 0
</div>

:''aString'' '''indexOfSeparator'''
:''aString'' '''indexOfSeparatorStartingAt:''' ''startIndex''
:''aString'' '''lastIndexOfSeparator'''
:''aString'' '''lastIndexOfSeparatorStartingAt:''' ''startIndex''
::Searches for the first/last whitespace character (Space, Tab, CR or NL). Returns 0 if not found.
::Example:
<div style="margin-left: 4em;">
'HELLO WORLD' indexOfSeparator
=> 6

'HELLO WORLD' indexOfSeparatorStartingAt: 7
=> 0

'HELLO abc World' lastIndexOfSeparator
=> 10

'HELLO abc World' lastIndexOfSeparatorStartingAt:10
=> 10

'HELLO abc World' lastIndexOfSeparatorStartingAt:9
=> 6
</div>
:''aString'' '''indexOfString:''' ''aSubstring'' [ '''startingAt:''' ''startIndex'' ]
:''aString'' '''lastIndexOfString:''' ''aSubstring'' [ '''startingAt:''' ''startIndex'' ]
::Returns the first/last index of an element (a character). Returns 0 if not found.
::Example:
<div style="margin-left: 4em;">
'HELLO' indexOfString:'LL'
=> 3

'HELLO' indexOfString: 'LX'
=> 0

'HELLO BELLO' lastIndexOfString: 'LL'
=> 9
</div>
:''aString'' '''includesString:''' ''aSubstring'' [ '''caseSensitive:''' ''boolean'' ]
::Returns true if ''aString'' contains the sub-string ''aSubstring''; false otherwise.
::Example:
<div style="margin-left: 4em;">
'HELLO' includesString:'LL'
=> true

'HELLO' includesString: 'll'
=> false

'HELLO' includesString: 'll' caseSensitive: false
=> true
</div>

=== Pattern Matching ===

Be reminded that there are two match algorithms available: the simpler GLOB pattern matcher (which resembles the way shell and cmd.com do filename matching), and the more complicated but also much more powerful REGEX matcher.
The most obvious difference is that in GLOB, the star "<CODE>*</CODE>" matches any string, including the empty string, whereas in REGEX, the star matches the PREVIOUS pattern zero or multiple times.
 
Thus, the simple GLOB pattern "<CODE>*.c</CODE>" (to match C-filenames) has to be written as "<CODE>.*\.c</CODE>" in REGEX
(because in regex, "<CODE>.</CODE>" matches ANY character, the star repeats it, and the next "<CODE>.</CODE>" has to be escaped because it would otherwise stand for "any character").
 If you are new to these concepts, please read the documentation on [[Regex Pattern Info#GLOB_Patterns|GLOB]] and [[Regex Pattern Info#Regex_Patterns|REGEX]] patterns.

The following are the most useful API entries (but the browser will show a few more):

==== GLOB Pattern Matching ====

:''aString'' '''matches:''' ''patternString'' [ '''caseSensitive:''' ''boolean'' ]
::True if a string matches a [[Regex Pattern Info|GLOB match pattern]].
::Example:
<div style="margin-left: 4em;">
'HELLO world' matches: 'HE*'
=> true

'HELLO world' matches: 'he*'
=> false

'HELLO world' matches: 'he*' caseSensitive: false
=> true
</div>

:''patternStrings'' '''compoundMatch:''' ''aString'' [ '''caseSensitive:''' ''boolean'' ]
::True if a string matches any pattern in patternStrings, which contains multiple [[Regex Pattern Info|GLOB match patterns]] separated by semicolon.
::Useful eg. to verify a string against multiple file extensions (eg. <code>'*.txt;*.doc;*.pdf' compoundMatch: aFilename</code>).
::Example:
<div style="margin-left: 4em;">
'f*;b*' compoundMatch:'foo'
=> true

'f*;b*' compoundMatch:'bar'
=> true

'f*;b*' compoundMatch:'xxx'
=> false
</div>

==== REGEX Pattern Matching ====

:''aString'' '''matchesRegex:''' ''patternString'' [ '''caseSensitive:''' ''boolean'' ]
::True if a string matches a [[Regex Pattern Info|regex pattern]].
::Example
<div style="margin-left: 4em;">
'HELLO world' matchesRegex: 'H.*O'
=> true

'HELLO world' matchesRegex: 'h.*o'
=> false

'HELLO world' matchesRegex: 'h.*o' caseSensitive: false
=> true

('myFile.txt' asFilename contents) select:[:line |
line matchesRegex:'[0-9]+\:.*'
]
=> all lines from the file which start with a number followed by a colon.
</div>

:''patternString'' '''regexMatchesIn:''' ''aString''
::Returns a collection containing all [[Regex Pattern Info|regex]] matching substrings.
::Example
<div style="margin-left: 4em;">
'[0-9]+' regexMatchesIn: '1234 abcd 3456 defg'
=> OrderedCollection('1234' '3456')
</div>

:''aString'' '''subExpressionsInRegex:''' ''patternString'' '''caseSensitive:''' ''boolean''
::Returns a collection containing the individual partial matches. Partials are [[Regex Pattern Info|regex]] subexpressions in parentheses.
::Example
<div style="margin-left: 4em;">
'1234abc3456' subExpressionsInRegex: '([0-9]+)abc([0-9]+)' caseSensitive:false
=> OrderedCollection('1234' '3456')

'123 abc xyz :bla' subExpressionsInRegex: '([0-9]+).*(\:.*)' caseSensitive:false
=> OrderedCollection('123' 'bla')
</div>
::Notice that ':' is a special character in the pattern and must therefore be escaped with a backslash.

=== Converting ===

:''aString'' '''asByteArray'''
::Returns a byte array containing the codePoints (Unicode codes).
::The characters should be within the ISO8859 range 0x00 .. 0xFF.
::If they are not, a byte array containing the wide characters is returned (to be exact: in the machine's native byte order, which is low byte first on x86 cpus).
::Example:
<div style="margin-left: 4em;">
'abc123' asByteArray
=> #[97 98 99 49 50 51]

'äöü' asByteArray
=> #[228 246 252]

c'abc\u2022123' asByteArray
=> #[97 0 98 0 99 0 34 32 49 0 50 0 51 0]
</div>
:''aString'' '''asFilename'''
::Returns a filename instance, which provides functions to operate on files and directories. See [[#Filename | "Filename protocol"]] for its functions.
::Example:
<div style="margin-left: 4em;">
'c:\data.txt' asFilename modificationTime
=> 2017-07-28 10:31:23

'/etc' asFilename exists
=> true
</div>
:''aStringWithMultipleLines'' '''asCollectionOfLines'''
::Returns a collection of strings, each containing one line from the original string. Handles any combination of CR, LF or CRLF as line separator. The resulting line-collection can then be further processed using functions from the [[#Collection | Collection protocol]].
::Example:
<div style="margin-left: 4em;">
'data.txt' asFilename contents asCollectionOfLines
=> #( 'line1' 'line2' 'line3' ... )
</div>
:''aString'' '''asCollectionOfWords'''
::Returns a collection of strings, each containing one word from the original string. Words are separated by whitespace (space, tab or CR/LF).
::Example:
<div style="margin-left: 4em;">
'hello bla bla world' asCollectionOfWords
=> #( 'hello' 'bla' 'bla' 'world' )
</div>

=== Encoding / Decoding ===

:''aString'' '''utf8Encoded'''
:''aString'' '''utf8Decoded'''
::Encode / decode into/from utf8 encoding.
::Example:
<div style="margin-left: 4em;">
'äöü' utf8Encoded
=> 'Ã¤Ã¶Ã¼'

'äöü' utf8Encoded asByteArray
=> #[195 164 195 182 195 188]

'äöü' utf8Encoded utf8Decoded
=> 'äöü'
</div>

:''aString'' '''utf16Encoded'''
::Encode into an utf16 encoded two byte string (ie. still a vector of characters), caring for characters above codepoint 0xFFFF. This can then be further converted to a vector of bytes in BE (big end) or LE (low end) order (see below).
::Example:
<div style="margin-left: 4em;">
'hello äöü' utf16Encoded encodeInto:#utfLE16
=> #[104 0 101 0 108 0 108 0 111 0 32 0 228 0 246 0 252 0]
</div>

:''aString'' '''encodeInto:''' ''nameOfEncoding''
:''aString'' '''decodeFrom:''' ''nameOfEncoding''
::Similar to the above, but ''nameOfEncoding'' gives the encoding's name (as symbol). Supported encodings are: #utf, #utf16BE, #utf16LE, #iso8859-1 to #iso8859-8, #iso8859-15, #iso8859-16, #koi7, #cp437, #cp850, #cp1250, #cp1252, #jis7, #gb, #big5, #ebcdic.

:''aString'' '''encodeFrom:''' ''nameOfEncoding1'' '''into:''' ''nameOfEncoding2''
::to transcode from one encoding into another. E.g. "someString encodeFrom:#cp850 into:#koi7" would recode from the Windows codepage 850 into cyrillic koi7.

:aString'' '''base64Encoded'''
:''aString'' '''base64Decoded'''
:''aString'' '''base64DecodedString'''
::Encode / decode into/from base64 encoding.
::Example:
<div style="margin-left: 4em;">
'äöü' base64Encoded
=> '5Pb8'

'äöü' base64Encoded asByteArray
=> #[53 80 98 56]

'äöü' base64Encoded base64Decoded
=> #[228 246 252]

'äöü' base64Encoded base64DecodedString
=> 'äöü'

'äöü' base64Encoded base64Decoded asString
=> 'äöü'
</div>

=== Hashing ===

See [[Cryptographic_API_Functions/en|Cryptographic API Functions]].

Collection API Functions

2026-02-23T10:45:34Z

Sv: Änderung übernommen aus altem Wiki von cg, 16.2.26

This document lists most useful (and most often needed) functions.
Be aware, that there are many more to be found in either the class references or via the builtin [[Tools_ClassBrowser/en | class browser]].

Reference: [http://live.exept.de/ClassDoc/classDocOf:,Collection Collection]

[[Useful API Functions | Back to Useful API Functions]]

[[Datei:point_right.png|20px]] Notice: except when written otherwise, all indices are 1-based. Valid indices range from 1 to the collection's size (as eg. in Mathematica, but not as in C, Java or Python).
 In Smalltalk, the first element has number 1, and the N'th element of a collection has number N.
 Also notice: String and ByteArray are subclasses of Collection, which means that most of the functions listed below can also be applied to sequences of characters and bytes.

== Most Useful Subclasses ==
:<CODE>Array</CODE>
:: a collection of (references to) other objects. An array can hold on any other object type, even mixed, which means that the elements of an array can be instances of different classes. Technically an array holds references (aka pointers) to its elements, not their contents. Arrays are fixed in size; this means that once created, you cannot add or remove elements (1).

:<CODE>OrderedCollection</CODE>
:: similar to an Array, these allow fast add- and removal at either end. They can therefore also be used as Stacks or Queues (although there are subclasses named "Queue" and "Stack", which solely exist to make their purpose clear and explicitly documented).

:<CODE>String</CODE>
:: a sequence of characters. Expecco supports 8, 16 and 32 bit strings. The internal encoding of all strings is always Unicode. Internally, strings are never kept in any compressed UTF8 or similar fashion. Only when loaded from or stored into external files or streams will there be an encoding. A number of encoders is found under the CharacterEncoder class. Although Strings look like Arrays of Characters to the outside world, they use a more compact internal storage format (1, 2 or 4 byte per character, instead of the 4 or 8 byte pointer as used by Array).

:<CODE>ByteArray</CODE>
:: a sequence of small unsigned 8 bit numbers (aka "bytes"). The class side protocol adds a number of instance creation methods, for example to read a hex encoded or Base64 encoded string. They also use a more compact storage format (1 byte per element).

:<CODE>Float32Array</CODE>, <CODE>Float64Array</CODE>
:: a sequence of IEEE floating point numbers. These are mostly used to store bulk data, such as mesurement values and/or for data interchange with bridges.

:<CODE>Dictionary</CODE>
:: a dictionary (also known as "HashTable" in other languages) will associate values to keys, where the key can be an arbitrary object. There are a number of specialized subclasses, such as CacheDictionary, CacheDictionaryWithLimitedLifeTime, IdentityDictionary, Virtual- and PluggableDictionary. The last one lets you specify your own configurable hash- and compare functions. The VirtualDictionary is a complete mock, where you can plug in any action (Smalltalk-block) for access.

:<CODE>Interval</CODE>
:: an interval (also known as "Range" in eg. Python) mimics a collection on the outside, but only keeps the first and last element inside, computing all elements on the fly. There is also a companion class called "GeometricSeries" which behaves similar, but computes elements via a multiplication factor instead of an addition step.

:<CODE>Tree</CODE>, <CODE>Queue</CODE>, <CODE>PriorityQueue</CODE> <CODE>SharedQueue</CODE>, ...
:: there are many other collections for special uses. We recommend you to open a systemBrowser and look at the examples provided on the class side (typically found under documentation - examples).

Notes:
1) it is actually possible to add or remove elements. However, for array instances, this is a very expensive operation and you will therefore get a harsh warning on the Transcript if you do.

== Common Protocol ==
This common protocol is ortogonally understood by all subclasses, including regular Array, ByteArray, Dictionary (Hashtable), Set and String. Although, some functions might be redefined in subclasses for performance reasons.

=== Creation ===
Collection instances are created by sending a variant of the "<code>new</code>" message to the class,
or by converting from another collection class.

:<CODE>Array</CODE> '''new:''' ''size''
:<CODE>ByteArray</CODE> '''new:''' ''size'' (and many others)
:<CODE>OrderedCollection</CODE> '''new'''
:<CODE>SortedCollection</CODE> '''new'''
:<CODE>Set</CODE> '''new'''
:<CODE>Dictionary</CODE> '''new'''
:<CODE>Dictionary</CODE> '''forCaseInsensitiveKeys'''
::OrderedCollection and Dictionary and their subclasses also understand the '''new:''' message with a size argument,
::[[Datei:point_right.png|20px]] but notice the different behavior as compared to Array's behavior:
:::for <CODE>Array</CODE> (and its subclasses), the size argument defines the size of the instantiated Array (which is fixed thereafter); and the array is filled wirth nils.
:::for <CODE>OrderedCollection</CODE> and<CODE>Dictionary</CODE> (and their subclasses), the size argument defines the number of preallocated slots in the collection; however, the logical size of it is zero (i.e. it is empty).
::[[Datei:point_right.png|20px]] In general:
:::if the collection class has a variable number of elements, the size given to the <code>new:</code> method is the preallocation size, whereas for fixed size collections, its the actual size (and the elements are initialized with nil or zero in the number containers).
::
::This is a somewhat irritating behavior due to historic reasons within the Smalltalk language (backward compatibility).
:: Use '''newWithSize:''' to get the same behavior:
:<CODE>OrderedCollection</CODE> '''newWithSize:''' ''size''
::creates a new ordered collection instance with ''size'' nil elements inside.

::Examples:
<div style="margin-left: 4em;">
a := Array new:5.
a
=> #(nil nil nil nil nil)

oc := OrderedCollection new:5.
oc
=> OrderedCollection()

oc := OrderedCollection newWithSize:5.
oc
=> OrderedCollection(nil nil nil nil nil)
</div>

Creation is also possible with an initial fill value:
:<CODE>Array</CODE> '''new:''' ''size'' '''withAll:''' ''initialValue''
::Examples:
<div style="margin-left: 4em;">
a := Array new:3 withAll:0.
a
=> #(0 0 0)
</div>

Or by taking the contents from another collection:
:<CODE>OrderedCollection</CODE> '''newFrom:''' ''anotherCollection''

ByteArray offers a few extra instance creators:
:<CODE>ByteArray</CODE> '''fromHexString:''' ''aString''
:: eg. <CODE>ByteArray fromHexString:'01FF02EE03AF'</CODE>
:: => #[1 255 2 238 3 175]
:<CODE>ByteArray</CODE> '''fromHexString:''' ''aString'' '''withSeparator:''' ''sepChar''
:: eg. <CODE>ByteArray fromHexString:'12:34:FE:FF' withSeparator:$:</CODE>
:: => #[18 52 254 255]

=== Accessing ===

:''aCollection'' '''size'''
:''aCollection''.'''size'''() [JS]
::Returns the number of elements in the collection (i.e. its length).
::Example:
<div style="margin-left: 4em;">
'hello world' size
=> 11

#(1 2 3) size
=> 3
</div>

:''aCollection'' '''at:''' ''index''
:''aCollection'' '''[''' ''índex'' ''']'''   [JS or ST]
::Returns the element at an index (1 based).
::Depending on the type of collection, this will be a numeric index (Array, OrderedCollection) or a general access key (Dictionary, OrderedDictionary). Example:
<div style="margin-left: 4em;">
'hello world' at:2
=> $e "/ (Notice: the dollar-char notation represents a character constant in Smalltalk)

'hello world'[5]
=> $o

#(90 4 50 20 99) asSortedCollection at:2
=> 20
</div>
[[Datei:point_right.png|20px]] Be reminded: indices are 1-based. Valid indices range from 1 to the collection's size.

:''aCollection'' '''at:''' ''index'' '''put:''' ''newValue'' => void
:''aCollection'' '''[''' ''índex'' ''']''' := ''newValue''  [ST]
:''aCollection'' '''[''' ''índex'' ''']''' = ''newValue''  [JS]
::Changes the element at an index (1 based).
::Depending on the type of collection, this will be a numeric index (Array, OrderedCollection) or a general access key (Dictionary, OrderedDictionary).
;; Example:
<div style="margin-left: 4em;">
s := 'hello world' copy. "/ (Notice: use a copy here, because constants are immutable)
s at:2 put:$*.
s
=> 'h*llo world'

c := #(90 4 50 20 99) asOrderedCollection.
c at:2 put:-1.
c
=> OrderedCollection(90 -1 50 20 99)

s := 'hello world' copy. "/ (Notice: use a copy here, because constants are immutable)
s[5] := $O.
s
=> 'hellO world'
</div>
Notice: It is in general not a good idea to use the value returned by "at:put: calls; it will be the stored value, not the collection. So do not write "coll := (Array new:1) at:1 put:something.", unless you want ''something'' to be stored in ''coll'.

=== Copy and Replacing ===
These are functional (i.e. non-destructive) operations, meaning that a new collection instance is returned and the original is not modified.
 There are also destructive variants (without a 'copy' in the name), which are not documented here, as their use is considered to be "bad style".

:''aCollection'' '''copyReplaceAll:''' ''element'' '''with:''' ''newElement''
::returns a copy of ''aCollection'' where all occurrences of ''oldElement'' have been replaced by ''newElement''.
::Examples:
<div style="margin-left: 4em;">
'abcdefabc' copyReplaceAll: $a with: $A
=> 'AbcdefAbc'

#(1 2 3 4) copyReplaceAll: 1 with: 100
=> #(100 2 3 4)
</div>

:''aCollection'' '''copyReplaceAll:''' ''element'' '''withAll:''' ''newElements''
::returns a copy of ''aCollection'' where ''newElements'' have been sliced in, whereever ''oldElement'' was encountered.
::Giving an empty replacement collection has the same effect as '''copyWithout:'''.
::Examples:
<div style="margin-left: 4em;">
'abcdefabc' copyReplaceAll: $a withAll: 'XXX'
=> 'XXXbcdefXXXbc'

'abcdefabc' copyReplaceAll: $a withAll: ''
=> 'bcdefbc'

#(1 2 3 4) copyReplaceAll: 1 withAll: #(100 200 300)
=> #(100 200 300 2 3 4)
</div>

:''aCollection'' '''copyWithout:''' ''element''
::returns a copy of ''aCollection'' where ''element'' have been removed.
::Examples:
<div style="margin-left: 4em;">
'abcdefabc' copyWithout: $a
=> 'bcdefbc'

#(1 2 3 4) copyWithout: 1
=> #(2 3 4)
</div>

=== Copying by Numeric Index ===
These functions are applicable to collections with a numeric index (i.e. Array, OrderedCollection, ByteArray, String, SortedCollection, FloatArray, DoubleArray, etc.).

:''aCollection'' '''copyFrom:''' ''startIndex'' '''to:''' ''endIndex''
:''aCollection''.'''copyFrom_to'''( ''startIndex'', ''endIndex'' )   [JS]
::Copies elements from a start index to an end index (both being 1-based indices). Example:
<div style="margin-left: 4em;">
'hello world' copyFrom:1 to:5.
=> 'hello'

#(10 20 30 40 50 60 70) copyFrom:1 to:5.
=> #(10 20 30 40 50)

(10 to: 100 by: 10) copyFrom:1 to:3.
=> #(10 20 30)
</div>

:''aCollection'' '''copyFrom:''' ''startIndex'' '''count:''' ''numChars''
:''aCollection''.'''copyFrom_count'''( ''startIndex'', ''numChars'' )   [JS]
::Copies a number of elements starting at the given index.
::Example: see example in [[String API Functions | String]]

:''aCollection'' '''copyFrom:''' ''startIndex'''
:''aCollection''.'''copyFrom'''( ''startIndex'' )   [JS]
::Copies from the given index to the end.
::Example: see example in [[String API Functions | String]]

:''aCollection'' '''copyTo:''' ''endIndex''
:''aCollection''.'''copyTo'''( ''endIndex'' )   [JS]
::Copies from the start to the given index.
::Example: see example in [[String API Functions | String]]

:''aCollection'' '''copyLast:''' ''count''
:''aCollection''.'''copyLast'''( ''count'' )   [JS]
::Copies the last count characters.
::Example: see example in [[String API Functions | String]]

:''aCollection'' '''copyButFirst:''' ''count''
:''aCollection''.'''copyButFirst'''( ''count'' )   [JS]
::Copies except for the first count characters.
::Example: see example in [[String API Functions | String]]

:''aCollection'' '''copyButLast:''' ''count''
:''aCollection''.'''copyButLast'''( ''count'' )   [JS]
::Copies except for the last count characters.
::Example: see example in [[String API Functions | String]]

:''collection1'' ''',''' ''collection2'' (The comma operator in Smalltalk)
::Concatenates arbitrary collections Example:
<div style="margin-left: 4em;">
#[10 20 30 40] , #[50 60 70 80]
=> #[10 20 30 40 50 60 70 80]

'Hello' , 'World'
=> 'Hello World'

(1 to:5) , (20 to:25) , #(88 99)
=> OrderedCollection(1 2 3 4 5 20 21 22 23 24 25 88 99)

(2 to:10 by:2) , (20 to:10 by:-2)
=> OrderedCollection(2 4 6 8 10 20 18 16 14 12 10)
</div>

=== Splitting ===

:''aCollection'' '''splitBy:''' ''anElement'' => collection
:''aCollection''.'''splitBy'''( ''anElement'' )   [JS]
::Splits a collection into pieces, given a splitting element. Example:
<div style="margin-left: 4em;">
#(10 11 12 0 20 22 24 0 1 2 3 0 50) splitBy: 0
=> #( #(10 11 12) #(20 22 24) #(1 2 3) #(50) ). <- this is an array of arrays
</div>

:''aCollection'' '''splitForSize:''' ''pieceSize'' => collection
::Splits a collection into pieces of a given size (the last returned piece might be smaller). Example:
<div style="margin-left: 4em;">
#(10 11 12 0 20 22 24 0 1 99) splitForSize: 3
=> #( #(10 11 12) #(0 20 22) #(24 0 1) #(99) ). <- this is an array of arrays
</div>

:''aCollection'' '''splitOn:''' ''element''
:''aCollection'' '''splitOn:''' ''splitCollection''
:''aCollection'' '''splitOn:''' [ :el | ''<condition-expression on el>'' ]
:''aCollection''.'''splitOn'''( ''element'' )   [JS]
:''aCollection''.'''splitOn'''( ''splitCollection'' )   [JS]
:''aCollection''.'''splitOn'''( (el) => ''<condition-expression on el>'' )   [JS]
::Splits a collection into pieces, given a splitter.
::The splitter may be a single element, a collection of elements or a block, which returns true to split.
::This is a more general version of the above "splitBy:", for complex splits.

=== Comparing ===

:''aCollection'' '''startsWith:''' ''prefixCollection'' [ '''caseSensitive:''' ''bool'' ] => bool
:''aCollection''.'''startsWith'''( ''prefixCollection'' )   [JS]
:''aCollection''.'''startsWith_caseSensitive'''( ''prefixCollection'', ''bool'' ) [JS]
::Checks if a collection starts with the same elements as another collection.

:''aCollection'' '''endsWith:''' ''suffixCollection'' [ '''caseSensitive:''' ''bool'' ] => bool
:''aCollection''.'''endsWith'''( ''suffixCollection'' )   [JS]
::Checks if a collection ends with the same elements as another collection.

=== Searching ===

:''aCollection'' '''indexOf:''' ''element''
:''aCollection'' '''lastIndexOf:''' ''element''
:''aCollection''.'''indexOf'''( ''element'' )   [JS]
:''aCollection''.'''lastIndexOf'''( ''element'' )   [JS]
::Returns the first/last index of an element. Returns 0 if not found. Example:
<div style="margin-left: 4em;">
'HELLO' indexOf: $L
=> 3

'HELLO' indexOf: $x
=> 0

'HELLO' lastIndexOf: $L
=> 4

#(1 2 3 1 2 3 1 2 3) lastIndexOf:2
=> 8
</div>

:''aCollection'' '''indexOf:''' ''element'' '''startingAt:''' ''startIndex''
:''aCollection'' '''lastIndexOf:''' ''element'' '''startingAt:''' ''startIndex''
:''aCollection''.'''indexOf_startingAt'''( ''element'', ''startIndex'' )   [JS]
:''aCollection''.'''lastIndexOf_startingAt'''( ''element'', ''startIndex'' )   [JS]
::Returns the next/previous index of an element given a search start index .
::Returns 0 if not found. Example:
<div style="margin-left: 4em;">
'HELLO WORLD' indexOf: $O startingAt: 6
=> 8

'HELLO WORLD' indexOf: $x startingAt: 6
=> 0

'HELLO WORLD' indexOf: $L startingAt: 6
=> 0

'HELLO WORLD' lastIndexOf: $O startingAt: 7
=> 5
</div>

:''aCollection'' '''indexOfAny:''' ''aCollectionOfElements'' [ '''startingAt:''' ''startIndex'' ]
:''aCollection'' '''lastIndexOfAny:''' ''aCollectionOfElements'' [ '''startingAt:''' ''startIndex'' ]
:''aCollection''.'''indexOfAny'''( ''aCollectionOfElements'' ) [JS]
:''aCollection''.'''indexOfAny_startingAt'''( ''aCollectionOfElements'', ''startIndex'' ) [JS]
:''aCollection''.'''lastIndexOfAny'''( ''aCollectionOfElements'' ) [JS]
:''aCollection''.'''lastIndexOfAny_startingAt'''( ''aCollectionOfElements'', ''startIndex'' ) [JS]
::Similar to the above, but searches for any element in the given argument collection.
::This may be a string (of characters) or an array or any other collection of characters. Returns 0 if not found.

:''aCollection'' '''indexOfString:''' ''aSubString'' [ '''caseSensitive:''' ''boolean'' ] [ '''startingAt:''' ''startIndex'' ]
:''aCollection'' '''lastIndexOfString:''' ''aSubString'' [ '''startingAt:''' ''startIndex'' ]
::Searches for a substring. Example:
<div style="margin-left: 4em;">
'HELLO WORLD Hello' indexOfString: 'LL'
=> 3

'HELLO WORLD Hello' indexOfString: 'll'
=> 0

'HELLO WORLD Hello' indexOfString: 'll' caseSensitive: false
=> 3

'HELLO WORLD hello' indexOfString: 'll' caseSensitive: false startingAt: 4
=> 15

'Hello World Hello' lastIndexOfString: 'll'
=> 15
</div>

=== Search & Extract ===
:''aCollection'' '''withoutPrefix:''' ''prefixCollection''
:''aCollection'' '''withoutPrefix:''' ''prefixCollection'' '''caseSensitive:''' ''aBoolean'' (Strings only)
::If ''aCollection'' starts with ''prefixCollection'', a copy of the remaining (right) elements is returned. Otherwise, the original collection is returned. Example:
<div style="margin-left: 4em;">
'SomeLongerString' withoutPrefix: 'Some'
=> 'LongerString'

'SomeLongerString' withoutPrefix: 'some'
=> 'SomeLongerString'

'SomeLongerString' withoutPrefix: 'some' caseSensitive: false
=> 'LongerString'

'anotherString' withoutPrefix: 'Some'
=> 'anotherString'

#(0 7 1 4 2 0 0 7 42) withoutPrefix: #(0 7 1 4 2)
=> #(0 0 7 42)
</div>

:''aCollection'' '''withoutSuffix:''' ''suffixCollection''
:''aCollection'' '''withoutSuffix:''' ''suffixCollection'' '''caseSensitive:''' ''aBoolean'' (Strings only)
::If ''aCollection'' ends with ''suffixCollection'', a copy of the left part is returned. Otherwise, the original collection is returned. Example:
<div style="margin-left: 4em;">
'foo.bar.baz' withoutSuffix: '.baz'
=> 'foo.bar'

'foo.bar.x' withoutSuffix: '.baz'
=> 'foo.bar.x'
Notice, for filenames, use ''withoutSuffix''.
</div>

:''aCollection'' '''upTo:''' ''elementToSearch''
:''aCollection'' '''restAfter:''' ''elementToSearch''
::Searches ''elementToSearch'' in ''aCollection'' and returns a copy of the left/right part. Example:
<div style="margin-left: 4em;">
'foo.bar.baz' upTo: $.
=> 'foo'

'foo.bar.x' restAfter: $.
=> 'bar.x'
</div>

:''aCollection'' '''upToAny:''' ''elementsToSearch''
:''aCollection'' '''restAfterAny:''' ''elementsToSearch''
::Searches ''aCollection'' for any element in ''elementsToSearch'' and returns a copy of the left/right part. Example:
<div style="margin-left: 4em;">
'foo;bar.baz' upToAny: '.,;'
=> 'foo'

'foo bar.x' restAfterAny: '.,;'
=> 'x'
</div>

:''aCollection'' '''upToAll:''' ''sliceToSearch''
:''aCollection'' '''restAfterAll:''' ''sliceToSearch''
::Searches for the ''sliceToSearch'' sequence in ''aCollection'' and returns a copy of the left/right part. Example:
<div style="margin-left: 4em;">
'name: foo age: 124' upToAll: 'age:'
=> 'name: foo '

'name: foo age: 124' restAfterAll: 'age:'
=> ' 124'
</div>

=== Converting ===

:''aCollection'' '''asByteArray'''
:''aCollection''.'''asByteArray'''() [JS]
::Returns a byte array containing the elements which must be integers in the ISO8859 range 0x00 .. 0xFF.

:''aCollection'' '''asSet'''
::Returns a set containing each element at most once.

:''aCollection'' '''asOrderedCollection'''
::Returns an ordered collection (that is a resizable dynamic array) containing the elements in the same order.

:''aCollection'' '''asSortedCollection'''
::Returns a sorted collection (that is a resizable dynamic collection which automatically sorts in additional elements).

=== Sorting ===

:''aCollection'' '''sorted'''
:''aCollection'' '''sortedBy:''' ''compareBlock''
::Returns a sorted copy of the collection (no side effect on the collection).
::If a condition argument (a block) is given, that should return true if the first argument is to come before the second. I.e. without a condition, the behavior is the same as "sortedBy:[:elA :elB | elA < elB]".
::Examples 
<div style="margin-left: 4em;">
''hello world'' '''sorted'''
=> ' dehllloorw'

#(10 2 99 17 -5 100) '''sorted'''
=> #(-5 2 10 17 99 100)

#(10 2 99 17 -5 100) '''sortedBy:[:a :b | a > b]'''
=> #(100 99 17 10 2 -5)

#('Paul' 'paula' 'Thomas' 'James' 'Emma') sorted
=> #('Emma' 'James' 'Paul' 'Thomas' 'paula')

#('Paul' 'paula' 'Thomas' 'James' 'Emma') sorted:[:a :b | a > b]
=> #('paula' 'Thomas' 'Paul' 'James' 'Emma')

#('Paul' 'paula' 'Thomas' 'James' 'Emma') sorted:[:a :b | a < b]
=> OrderedCollection('Emma' 'James' 'Paul' 'Thomas' 'paula')

#('Paul' 'paula' 'Thomas' 'James' 'Emma') sorted:[:a :b | a caselessBefore: b]
=> #('Emma' 'James' 'Paul' 'paula' 'Thomas')

#('Paul' 'paula' 'Thomas' 'James' 'Emma') sorted:[:a :b | b caselessBefore: a]
=> #('Thomas' 'paula' 'Paul' 'James' 'Emma')
</div>

:''aCollection'' '''sort'''
:''aCollection'' '''sort:''' ''compareBlock''
::Sorts the collection in place (i.e. has a side effect on the collection).

:''aCollection'' '''reversed'''
::Returns a copy with elements in reverse oerder
:''aCollection'' '''reverse'''
::Inplace reverts the elements (i.e. modifies the collection)

=== Enumerating ===
:In Smalltalk there is almost never a need to program a loop which fetches and processes elements. You should use the provided enumeration functions for that, both for readability and because some of them are highly optimized.

:''aCollection'' '''do:''' '''[''' :el | ... ''']'''
:''aCollection''.'''do:''' ( function(el) { ... } ) [JS] (Function notation)
:''aCollection''.'''do:''' ( (el) -> ...) [JS] (Lambda notation)
::evaluates the argument block for each element in the collection. The "do:" method is supported by all collections and even some non-collections (for example some widgets which present lists or text lines may also support the do: message to enumerate their contents).
::Examples 
<div style="margin-left: 4em;">
#(10 5 4 20 99) do:[:eachElement |
Transcript showCR: eachElement.
myFile nextPutLine:(eachElement hexPrintString).
]

#(10 5 4 20 99) sorted do:[:eachElement |
Transcript showCR: eachElement.
]

"/ info: "(nr1 to: nr2)" generates a range collection
"/ (called ''Interval'' in Smalltalk)
(1 to:10) do:[:each |
Transcript printf:'%3d: %4d\n' with:each with:(each * each).
]

"/ a kind of "ls" implementation: lists files of the current folder
'.' asFilename files do:[:eachFile |
Transcript showCR: eachFile.
]

"/ this prints the contents of each file
'.'asFilename files do:[:eachFile |
Transcript showCR: eachFile.
eachFile contents do:[:eachLine |
Transcript showCR: eachLine.
]
]

"/ the same but shorter and even faster...
'.'asFilename files do:[:eachFile |
Transcript showCR: eachFile.
Transcript showCR: eachFile contents.
]
</div>

:''aCollection'' '''keysAndValuesDo:''' '''[''' :k :el | ... ''']'''
:''aCollection'' '''doWithIndex:''' '''[''' :el :k | ... ''']'''
::evaluates the 2-argument block for each key and element in the collection. This is supported by all indexable collections. For arrays and other collections with a numeric index, that is provided as key. For dictionaries, the lookup key is provided.
::The ''doWithIndex:'' variant performs the same function, but provides the argument in reverse order into the block (syntactic sugar for readability).
::Examples 
<div style="margin-left: 4em;">
#(10 5 4 20 99) keysAndValuesDo:[:eachIndex :eachElement |
Transcript show: eachIndex.
Transcript show:' -> '.
Transcript showCR: eachElement.
]

d := Dictionary new.
d at:'foo' put:123.
d at:'bar' put:999.
d keysAndValuesDo:[:eachKey :eachElement |
Transcript show: eachKey .
Transcript show:' -> '.
Transcript showCR: eachElement.
]
</div>

:''aCollection'' '''collect:''' '''[''' :el | ... ''']'''
::evaluates the argument block for each element in the collection and collects the results, returning a new collection with all results (this is called "map" in other languages).
::Examples 
<div style="margin-left: 4em;">
'.' asFilename files collect:[:eachFile | eachFile fileSize].

Transcript showCR:
(1 to:10) collect:[:nr | nr * nr]
</div>

:''aCollection'' '''select:''' '''[''' :el | ... ''']'''
::evaluates the boolean argument block for each element in the collection and collects those elements for which the block returns true. I.e. this is filtering elements by a boolean condition.
::Examples 
<div style="margin-left: 4em;">
"/ lists files larger than 10000 bytes
'.' asFilename files select:[:eachFile | eachFile fileSize > 10000].

Transcript
showCR: 'even numbers:';
showCR: (1 to:100) select:[:nr | nr even]
</div>

:''aCollection'' '''reject:''' '''[''' :el | ... ''']'''
::similar to select, but this returns the complement: a new collection without elements for which the boolean argument block returns true.

:''aCollection'' '''count:''' '''[''' :el | ... ''']'''
::counts for how many elements the boolean argument block returns true.
::Examples 
<div style="margin-left: 4em;">
"/ how many files are larger than 10000 bytes
'.' asFilename files count:[:eachFile | eachFile fileSize > 10000].
</div>

:''aCollection'' '''detect:''' '''[''' :el | ... ''']'''
::find and return the first element for which the boolean argument block returns true. If none is found, an error is reported.

:''aCollection'' '''detect:''' '''[''' :el | ... ''']''' '''ifNone:''' ''replacementBlock''
::find and return the first element for which the boolean argument block returns true. If none is found, replacementBlock is evaluated and its value returned.
::Examples 
<div style="margin-left: 4em;">
#(1 2 3 4 5) detect:[:el | el > 10]
=> reports an error: no such element

#(1 2 3 4 5) detect:[:el | el > 10] ifNone:[99]
=> 99

#(1 2 3 4 5) detect:[:el | el > 10] ifNone:[ Dialog warn:'No such element'. nil]
=> nil. (after the warning is shown)
</div>

:''aCollection'' '''findFirst:''' '''[''' :el | ... ''']'''
:''aCollection'' '''findLast:''' '''[''' :el | ... ''']'''
::find the index of the first/last element for which the boolean condition block returns true. Returns 0 if no element matches the condition.
::Examples 
<div style="margin-left: 4em;">
#(15 2 -3 44 5.3) findFirst:[:el | el > 20]
=> 4 (the index of the found element)

'Hello World' findFirst:[:ch | ch isSeparator]
=> 6
</div>

:There are many more (hundreds) of additional useful enumeration messages to be found in the collection hierarchy. For example to enumerate in groups, stepping over elements, enumerating multiple collections together, enumerating in reverse order etc.
:For details, open a System Browser (via the "''Extras''" → "''Tools''" menu) and take look at the collection class and its subclasses.

:Also notice that Strings, NumberVectors, ByteArrays etc. also inherit from Collection; thus, all of those functions can also be applied to them.

Useful API Functions

2026-02-23T10:43:05Z

Sv: Änderung übernommen aus altem Wiki von cg, 16.2.26

This document lists most useful (and most often needed) classes and functions.
Be aware, that there are many more to be found in either the class references or via the builtin [[Tools_ClassBrowser/en | class browser]].

== [[String API Functions | String]] ==

Strings are sequences of characters. Expecco uses and supports the Unicode encoding standard and supports the whole unicode range. However, not all fonts will contain all characters, resulting in some missing characters being drawn with a replacement char (typically a box-like rectangle) in text windows. The concrete details depend on the operating system and the set of installed fonts.

String instances inherit a lot of functionality from String's superclasses: SequenceableCollection and Collection. Thus, all functions found there (enumeration, mapping, filtering, searching etc.) can also be applied to strings.

Read more: [[String_API_Functions|String API Functions]] 
Reference: [http://live.exept.de/ClassDoc/classDocOf:,String String]
inherits from: [http://live.exept.de/ClassDoc/classDocOf:,CharacterArray CharacterArray] and
[http://live.exept.de/ClassDoc/classDocOf:,SequenceableCollection SequenceableCollection] and [http://live.exept.de/ClassDoc/classDocOf:,Collection Collection]

== [[Collection API Functions | Collection]] ==

Collection is an abstract class, serving as a superclass for a number of useful concrete classes (such as Array, ByteArray, Set, Dictionary, Tree, SortedCollection, String etc.)
It is useful to get a feeling of the set of operations provided there (there are a lot!), so you should not have to reinvent the wheel.

Read more: [[Collection_API_Functions|Collection API Functions]] 
Reference: [http://live.exept.de/ClassDoc/classDocOf:,Collection Collection]

== [[Filename API Functions | Filename]] ==

Although strings could be used to represent file names and paths, expecco uses instances of a specialized class called "''Filename''" to represent those. Filename instances know about any details of the underlying operating system (such as the directory separator, any naming restrictions etc.) and also provide a number of useful functions for file and directory access. Filename provides a portable representation, so that code can run on both Windows and Unix unchanged (that is: use "/" in filenames when possible. On a Windows machine, these will be replaced internally by "\" characters).

Of course, there are still many differences between the systems, the most obvius being different pathes. For that, the Filiename class provides a number of accessors, for example to get the path to the home directory, the path to the temp folder etc. Do not hardcode any pathnames into your code or testSuite; instead either use the above mentioned accessors, or place the pathes into a global variable, so they can be both easily found and also easily overwritten by eg. the command line or a config file.

Read more: [[Filename_API_Functions|Filename API Functions]] 
Reference: [http://live.exept.de/ClassDoc/classDocOf:,Filename Filename]

== [[Stream API Functions | Stream]] ==

Streams can be internal (eg. reading from a String) or external (eg. a file stream, pipe or socket). Streams can be used to read bytewiese, character wise (with optional UTF decoding/encoding) or object-wise.
Most uses are with external streams, which are byte or character oriented: FileStream, PipeStream, Socket are examples.

Read more: [[Stream_API_Functions|Stream API Functions]] 
Reference: [http://live.exept.de/ClassDoc/classDocOf:,Stream Stream]

== [[Number API Functions | Number]] ==

Expecco supports a full numeric stack of numbers; both exact (integers and fractions) and inexact (IEEE floats in various precisions). Integer operations do not overflow or loose bits: expecco will automatically choose an appropriate representation to eg. be able to represent huge numbers.

Read more: [[Number_API_Functions|Number API Functions]] 
Reference: [http://live.exept.de/ClassDoc/classDocOf:,Number Number] and its subclasses
[http://live.exept.de/ClassDoc/classDocOf:,Integer Integer],
[http://live.exept.de/ClassDoc/classDocOf:,Float Float],
[http://live.exept.de/ClassDoc/classDocOf:,Fraction Fraction],
[http://live.exept.de/ClassDoc/classDocOf:,FixedPoint ScaledDecimal],
[http://live.exept.de/ClassDoc/classDocOf:,Complex Complex]

== [[Date & Time]] ==
Expecco provides a number of time related support classes: TimeDuration, Time, Date and Timestamp (aka. ''TimeAndDate'') for local, UTC and time zone specific. Although timestamps support picosecond precision, current operating systems will only provide milli- or microsecond resolution timestamps. However finer resolution values may come from exact measurement devices or be computed in technical/physical processes.

Read more: [[Date_and_Time_API_Functions|Date and Time API Functions]] 
Reference: [http://live.exept.de/ClassDoc/classDocOf:,Date Date], [http://live.exept.de/ClassDoc/classDocOf:,Time Time], [http://live.exept.de/ClassDoc/classDocOf:,Timestamp Timestamp], [http://live.exept.de/ClassDoc/classDocOf:,UtcTimestamp UtcTimestamp], [http://live.exept.de/ClassDoc/classDocOf:,TZTimestamp TZTimestamp], [http://live.exept.de/ClassDoc/classDocOf:,TimeDuration TimeDuration].

== [[PhysicalValues/en|Physical Values]] ==
Since 20.1, expecco supports an additional framework to represent physical values, such as mass (in kg), length (in meters), velocity, [[PhysicalValues/en#Acceleration|acceleration]], voltage, electric current etc.
 Beside being able to do arithmetic as in <code>3.0 kiloMeter / 20 minutes</code> (which gives "2.5 m/s") they can also be used for conversion between metric and imperial unit systems (eg. "<code>10 nauticalMiles asMeters</code>" gives the answer "18520 m" and "<code>15 inches asMilliMeters</code>" returns "381 mm").

Read more: [[PhysicalValues/en|PhysicalValues]] 

== [[Cryptographic_API_Functions/en | Cryptography]] ==

Algorithms for hashing, encryption and decryption, certificate handling etc.

Read more: [[Cryptographic_API_Functions/en|Cryptographic API Functions]]

Datatype Editor/en

2026-02-23T10:40:42Z

Sv: Änderung übernommen aus altem Wiki von cg, 16.2.26

==Introduction==
[[Datatype Element | Datatypes]] are attached to pins and environment variables, and usually presented by name in a datatype definition pull-down menu.
There are both builtin (hardwired) and user defined data types in expecco.
User defined datatypes are shown in those pull-down lists in a separate submenu of the type menu.

This editor is used to define new [[Datatype Element | datatypes]]. Builtin types cannot be modified.

==Type Kinds==
The ''kind'' specifies the kind of type and '''how''' it is defined. For example, there are vector types, enum types, struct types etc. These are described in more detail below.

There are multiple '''conceptional''' ways to define a new datatype:
* by enumerating its elements (enums; i.e. a set of values)
* as a subtype of an existing type (enum, range types)
* by combining elements of existing types (tuple, array, structure or union types)
* by explicit definition as a class or data structure (C-type, ST/X-class type)
* by referring to an existing class of the underlying framework (primary types)

Also, there are various '''syntactical''' representations, in which a type may be presented or imported:
* expecco type definition syntax
* XML / XSD / DTD / IDL
* C language struct syntax
* COBOL Copybook, Sun RPC IDL, COM-IDL, ASN.1

The set of options available in the editor depends on the expecco version (basic, pro, enterprise) and the set of available plugins (SWIFT, ASN.1, etc.), as some import formats are provided by additional plugins.

To define a type, first create a new datatype tree item, then choose an appropriate representation in the editor's "''Type-Kind''" list. A template showing the syntax of this type will be shown.

Change the template and press "''Accept''" to install the type. The second tab in the editor labeled "''Type Description''" shows the type's definition in expecco's internal type description language, which is usually only of interest to validate a type's correctness if an alien format was used to import a type definition. This format is described [[ #Formal BNF Description of the Expecco Type Syntax | below ]].

[[Datei:typeEditor1.png|600px|Datatype Editor]]

==Type Kinds (Semantic)==

===Primary Types===
These are builtin types (classes) of the underlying Smalltalk execution framework. For example, "<code>String</code>", "<code>Array</code>", "<code>Set</code>", "<code>Btree</code>", "<code>Dictionary</code>" or "<code>Number</code>" to name a few. There are thousands of classes available, but you will usually get along happily with only a few - if at all. However, you might need to know some, when referring to a framework inside expecco's underlying Smalltalk environment. For example, there are packages and classes to support protocols like FTP, HTTP, etc. or to process data, parse special file formats or provide cryptographic operations. Also, some expecco plugins and extensions come bundled with additional useful classes. These classes usually provide many additional API functions than provided in the standard library (it would be immensly big otherwise). And sometimes you can use these additional functions, so its good to know a little more.

The most common primary types are shortly listed in the [[Datatype Element | "Datatype documentation" ]].
For more details, please refer to the Smalltalk documentation, especially the [http://live.exept.de/doc/online/english/overview/basicClasses/TOP.html "Basic Classes Introduction"] and the [http://live.exept.de/ClassDoc "Online Class Documentation"] (containing full lists and documentation of all classes).

Even better: you can also open a class browser (found in "''Extras''" → "''Tools''") and look at the source code which often includes examples in their method comment. Another useful tool is the "MethodFinder" which lets you find functions which generate a particulal output (i.e. if you know what input you have, and what output you want, but you don't know where to search, this is the tool for you).

A number of primary types is available directly via the datatype menus, and there is no need to define them as a user type.
These predefined primary types include "<code>Integer</code>", "<code>Number</code>", "<code>String</code>", "<code>Boolean</code>" along with a few other often used types.
All other primary types can be defined as a ''user defined type'' in a textual type definition, where the class name is written in angle brackets, as in:
<PRE>
<String>
</PRE>or:
<PRE>
<Socket>
</PRE>

===Enumeration Types===
Data items are symbolic and members of a list of enumerated values (symbolic).
Unless quoted in single quotes, these names must consist of letters or digits or underline characters, and should start with a non-digit (to avoid confusion).

Typical examples are:
<PRE>
enum( red | green | blue)
</PRE>
or:
<PRE>
enum( male | female)
</PRE>
or:
<PRE>
enum( 'foo-a' | 'foo-b' | 'foo-c' | 'bar-a' | 'bar-b' )
</PRE>
The last example uses quotes around the element names, as these contain a special (non-alphanumeric) character.

===== Enum in Input Dialogs =====
When used as a freeze value or environment variable value, a combo list presenting only the valid enum elements is shown. By default, the values are sorted alphabetically in one single list. If your type consists of a large number of values, you may want to specify a grouping scheme.
[[Datei:Datatype enumOrder.png|mini]]
For example, the last of the above examples could be presented as either a single list with 5 items, or as a 2-item list ('foo' and 'bar') with submenus for each prefix. The menu/combolist grouping is specified in the datatype editor (at the bottom right of the editor).

===== Numeric Value of an Enum =====
Enum values can have an associated integer value, which is useful, if the type is actually a mapping of a corresponding C or Java type. For this, add an "<code>= <integerValue></code>" after the element's name to the above definition. Eg.:
<PRE>
enum ( foo | bar = 20 | baz | bla = 30 )
</PRE>
Will assign integer values to the enum elements.
Without explicit integer value, elements get auto-incremented values, starting with 0 (zero) or the next value from the previous enum element. Thus, in the above, "baz" will get the numeric value 21 assigned.

Elementary code can retrieve this integer value via "<code><type> integerValueOf: x</code>" in Smalltalk,
or "<code><type>.integerValueOf(x)</code>" in Javascript. There is also a standard library action to retrieve the numeric value ("<code>Convert [Enum-to-Integer]</code>").
These will return the following integer values:
0 (for x = 'foo'), 20 (for x = 'bar'), 21 for (x = 'baz') and 30 (for x = 'bla')

The reverse mapping from integer to symbolic is performed with
"<code><type> symbolicValueOf: x</code>" (Smalltalk),
"<code><type>.symbolicValueOf(x)</code>" (Javascript), or the library action
"<code>Convert [Integer-to-Enum]</code>".

Be aware that enum-typed datums are always string-like objects (actually: instances of Smalltalk's <code>Symbol</code> class). Thus, although the elements look like integers in a definition like "<code>(1 | 2 | 3)</code>", they are actually string like with an associated integer. Consider using a subrange or subset type, as described below, if you need integer datums.

Although not recommended, the same numeric value can be assigned to more than one symbol. However, a reverse mapping from numeric value to symbolic is then no longer possible.

===== Enum Definition pasted from a C-Header File =====
New in 18.2: 
In addition to the above definition format, enum types can also be defined as a list of C-define directives.
This makes it easier, to copy-paste a list of values from a C-header file. The format is described [[#Enum_Type_Definition_from_C-define_Directives | below]].

===Range Types===
A subrange of <code>Integer</code>, <code>Character</code> or Enum values. Used to limit the set of valid elements, given a previously defined or buitin base type. For example, a byte could be defined as:
<PRE>
range( <Integer> : 0 .. 255 )
</PRE>
and the set of lowercase letters can be defined as:
<PRE>
range( <Character> : $a .. $z )
</PRE>
[[Datei:point_right.png|20px]] Notice the dollar prefix, which designates a character constant in the Smalltalk language.

===Subset Types===
A subset of <code>Integer</code>, <code>Character</code> or Enum values. This is similar to a subrange, but allows for multiple ranges or individual elements to be listed.

For example, the set of alphanumeric characters plus underline could be defined as:
<PRE>
subset( <Character> : $a .. %z , $A .. $Z , $_ , $0 .. $9 )
</PRE>

A type which can take character values limited to the set of English vowels could be defined as:
<PRE>
subset( <Character> : $A , $E , $I , $O , $U , $a , $e , $i , $o , $u )
</PRE>

[[Datei:point_right.png|20px]] Again, notice the dollar prefix, which designates a character constant.

===Pattern Types===
(new with expecco 21.2) 
A constraint subset of <code>String</code> values. Constraint may be that the string matches
a glob or regex pattern, and/or that its size (number of characters) is within some limits.

For example, a type for strings not longer than 10 characters could be defined as:
<PRE>
String( maxLength: 10 )
</PRE>

A type for a string which starts with a letter can be defined as ([https://en.wikipedia.org/wiki/Glob_(programming) GLOB] pattern):
<PRE>
String( match: '[a-z]*')
</PRE>

or alternatively, using a [https://en.wikipedia.org/wiki/Regular_expression Regex] (instead of a GLOB pattern) as:
<PRE>
String( regex: '[a-z].*')
</PRE>

The constraint can be one of:
* '''minLength''': <n>
:the string must consist of at least <n> characters
* '''maxLength''': <n>
:may not be longer than <n> characters
* '''match''': '<glob pattern>'
: the strings must match the [https://en.wikipedia.org/wiki/Glob_(programming) GLOB] pattern
* '''regex''': '<pattern>'
: must match the [https://en.wikipedia.org/wiki/Regular_expression Regex] pattern

[[Datei:point_right.png|20px]] Be aware of the difference between GLOB and Regex patterns.

===Array Types===
Are defined as a homogeneous collection of elements, which are all of the same baseType. The number of elements is variable among instances.
The elements are accessible by a numeric index which is 1 based (both for Smalltalk and JavaScript elementary blocks). The standard library also provides 0-based indexing blocks, which is sometimes more convenient for C/Java programmers.


In a textual definition, array types consist of a basetype followed by "[]", as in:
<PRE>
<String>[] -- an array of Strings
</PRE>
or:
<PRE>
<Number>[] -- an array of Numbers
</PRE>
Notice that these are type Arrays, in contrast to the Smalltalk primary Array type, which allows any object as element. Event mixed within one array.

===Tuple Types===
Are defined as a non-homogeneous, fixed size vector of elements. Each element has a predefined type. The types may be different among elements, but all instances of the tuple type have the same number of elements and the same type of element at corresponding positions.

The elements are accessible by index (1..). Tuples are similar to compound types as described below. The difference is that tuples address the elements by index, whereas compounds address them by name. Tuples are also similar to array types, however, the number of elements is fixed in a tuple, whereas arrays can have an arbitrary number of elements, and the element types may be different if its a primary array or an array of Any), Otherwise in a typed array, all elements are of the same type.

In a textual description, a tuple is defined by listing the individual element types in parentheses.
For example, a tuple which might represent a 3D coordinate, could be defined as:
<PRE>
[ <Number> , <Number> , <Number> ]
</PRE>
or, a tuple which associates a name with an age and gender might be:
<PRE>
[ <String> , <Integer> , enum(M | F) ]
</PRE>
For the last example, it would probably be better to use a compound, which names the slots.

[[Datei:point_right.png|20px]] Notice, in previous versions of expecco, tuple types could also be defined in parenthesis "(...)", as opposed to brackets "[...]".
This is still supported in future versions, but not recommended for new type definitions (read the documentation on union types for an explanation).
No ambiguity exists if the definition starts with 'tuple', as in:
<PRE>
tuple( <Number> , <Number> , <Number> )
</PRE>

===Class Types===
A user defined class. Includes the instance's private slots (also called "''instance variables''"), and a set of operations (usually called "''methods''" or "''virtual functions''"). All of this information is stored with the test suite.
Instance slots are accessible by getter/setter method invocations.
Class types are defined by entering the class definition in a programming language (either expecco's JavaScript dialect or Smalltalk).

Private class definitions allow for almost any functionality to be defined, but require some programming skills. For an introduction to programming, please refer to the [http://live.exept.de/doc/online/english/TOP.html "Online Documentation"],
the [http://live.exept.de/doc/online/english/getstart/tutorial.html "Beginners Introduction & Tutorial"],
and the [http://live.exept.de/doc/books/JoyOfST/IntroToST.html "Smalltalk Tutorial"],.

===Compound Types===
A collection of named slots. Is similar to a Class Type without operations (actually, that is how the system represents them internally).
The elements are accessible by name or keyed access, using the name as key (i.e. like a dictionary/hashtable).

In a textual definition, list the names and types of the individual elements in braces; for example, a person record might be defined as:
<PRE>
{
firstame : <String>
lastName : <String>
age : <Integer>
gender : enum(M | F)
}
</PRE>

Field definitions may optionally be terminated by a ";" (semicolon) character to make the definition more readable.
I.e. the following defines the same type as the above:
<PRE>
{
firstame : <String>;
lastName : <String>;
age : <Integer>;
gender : enum(M | F);
}
</PRE>
Also, for backward compatibility, a terminating "," (comma) character is allowed, but no longer recommended.

Compound type definitions can also be imported from various other formats, such as DTD, XML, C-header files etc.

==== Getters ====
In elementary code blocks, field values of an instance are accessed via getter calls which are named like the field.
 For example, given an instance of the above named "<code>c</code>", the "''lastName''" field can be fetched in Smalltalk code with any of:
c lastName "/ calling the getter
c at:'lastName' "/ using collection protocol
c['lastName'] "/ using collection protocol
or in JavaScript code with:
c.lastName() // calling the getter
c.lastName // (virtual) slot access
c['lastName'] // using collection protocol
c["lastName"] // using collection protocol
Notice, that double quotes in Smalltalk are comment delimiters, whereas in JavaScript they are also string delimiters.

==== Setters ====
Elementary code can change a field's value via setter calls.
 For the above example, these would be in Smalltalk:
c lastName:newValue
c at:'lastName' put:newValue
c['lastName'] := newValue
and in JavaScript:
c.lastName(newValue)
c['lastName'] := newValue
c["lastName"] := newValue

==== Generating Action Blocks to Access Fields and Create Instances ====
[[Datei:CompoundCreateActions.png|mini]]
[[Datei:CompoundCreateActions2.png|mini]]
The tree-item menu of a compound type contains entries to generate field-setter, field getter and creation actions (under "''Refactoring''" - "''Generate''").
 

 

 

 

After that, you'll find actions to create an instance, to extract and to set fields.

These are elementary actions, which use the above listed getter/setter calls. They can of course be further modified if additional checks or processing is needed. Notice that to access fields of a compound object, you can also use the "''Collection [elementAt]''" and "''Collection [elementAtPut]''" actions, using the field names as index.

===Union Types===
The instance can be an instance from a number of other types.
In a textual definition, list the possible element types, separated by a vetical bar, as in:
<PRE>
( <Filename> | <String> | <URL> )
</PRE>
or, alternatively:
<PRE>
union ( <Filename> | <String> | <URL> )
</PRE>

there is no explicit discriminator stored with the value. However, due to the run-time type information, it is possible in an elementary block to determine the type of value passed in, via the <CODE>class</CODE> or <CODE>isXXX</CODE> or <CODE>isKindOf:</CODE> protocols.

[[Datei:point_right.png|20px]] Notice that for a single element union type (eg. "<code>( String )</code>") the interpretation was ambiguous in previous expecco versions, as it could also be interpreted as a tuple with a single String element. Therefore, the syntax for tuple types was changed to use square brackets, but still supporting the previous regular parentheses syntax. There is no ambiguity when more than one element is present; however, for single element types, the datatype parser will (currently) read this as a single-type union type.

To avoid this ambiguity, the old parenthesis-syntax should no longer be used for tuples (prefixing with 'union' also solves this).

=== Additional Special Types ===

==== Datatype Type ====
Instances are datatypes known to the project. Datatype-types are typically used as input pin type of collection-instantiation blocks.
As a freeze value, the list of known types is presented in a combolist.
In a textual definition, the keyword "<code>datatype</code>" is used:
datatype

==== Constraint Datatype Type ====
A datatype type can be constraint to a subset of types, by defining it as:
datatype ( <constraint> )
where <constraint> is either the name of another type:
* <compatTypeName> - constraint to types which are compatible with a type named <compatTypeName>
or a selector from one of:
* <code>isArrayType</code> - for types which have integer-indexable slots
* <code>isCTypeType</code> - for C-defined types
* <code>isCEnumType</code> - for C enum types
* <code>isCStructType</code> - for C-defined struct types
* <code>isCUnionType</code> - for C-defined union types
* <code>isCollectionPrimaryType</code> - for subtypes of Collection (i.e. Dictionary, Set, OrderedCollection etc.)
* <code>isCompoundType</code> - for compound types
* <code>isEnumType</code> - for enum types
* <code>isNumberPrimaryType</code> - for subtypes of Number (i.e. Float, Integer, Fraction, FixedPoint)
* <code>isPrimaryType</code> - for any primary type
* <code>isStreamPrimaryType</code> - for subtypes of Stream
* <code>isTupleType</code> - for any tuple type
* <code>isUnionType</code> - for any union type
* <code>isUserDefinedDatatype</code> - for all user defined types (i.e. those in the current suite)
* <code>isWellKnownDatatype</code> - for all builtin (i.e. not user defined) types. These types will always be present, whereas user defined types are those defined in the current suite

or a selector plus string argument from one of:
* <code>nameMatches:</code> ''globPattern''
* <code>nameMatchesRegex:</code> ''regexPattern''

Constrained datatypes should be used by the StandardLibraries only, and are used to limit the input values of some instance creation actions.
For example, the "New Collection" action has an input pin, which defines the type of collection to be created.
This pin has the type: "<code>datatype( isCollectionPrimaryType )</code>".

Examples:
datatype ( Integer ) -- a type whose instances are all datatypes which are compatible with the Integer class
datatype ( isCTypeType ) -- a type whose instances are all known C-types
datatype ( isCStructType ) -- a type representing all known C struct types
datatype ( nameMatches: 'DPU*' ) -- a type representing all types which match this name

Notice that the freeze value of a datatype-typed pin (and also values flowing in and out of such pins) are data types; not values (although datatypes are also objects/values in the technical sense).

==== Monitor Types ====
A monitor is a special builtin object which observes an object and sends out change notifications to interested stakeholders when it changes its contents. Monitors are used to allow external QA systems (such as expecco ALM) to monitor and display changing expecco variables in real time.

==== Resource, Skill, Library and ActivityLog Types ====
Represent instances of resources and skills. These are builtin types used by expecco itself.

==== Port Types ====
These are not yet used but present for future TTCN3 support.

==Type Popup-Menu Organisation==
In addition to the definition of the type, the editor provides control on
where and how the type will be presented in type popup menus and pull down lists.
===Group===
If you attach a group name to the type, it will be grouped into a such-named submenu below a pin's or variable's datatype popup menu.

===Enum Freeze-Value Menu Organisation===
When freezing an enum-typed pin or choosing an enum variable's default value,
by default the elements are presented in one list. This list may get long and you may want to organize them into a hierarchical set of submenus and/or control how they are sorted.

For example, if the enum elements represent commands to a controller, they might be named after commands, like "power_on", "power_off", "power_low", "turn_left", "turn_right" etc.
 In this case, you may want to organize the freeze menu into two submenus, one for all "power_XXX" values, another for all "turn_XXX"values etc.

The editor's "''Freeze Menu Organization''" at the lower right gives you a number of options to organize your menus and how to sort the elements. Use that, if you have more than (say) 10 or 15 elements in an enum. Click on the "''Test''" button to see how the menu will be shown later.
=====Sort Order=====
By default, elements will be presented in the order of the type definition.
 The choices are:
* normal - use the default sort order
* sortAlphabetical - sort by name
* sortNatural - numeric suffixes are sorted by value (i.e. 'a10' comes after 'a2')
* sortByValue - sort by the associated value; not the symbolic name
=====Hierarchical Menu=====
The other options control where the symbolic names are split and grouped into submenus.

==Type Representation (Syntax)==

Various textual representations are possible; some are already built into the base expecco system, others are addons and present if certain plugins are installed.

=== Formal BNF Description of the Expecco Type Syntax ===

Expecco provides its own native type-description language, with an easy to understand and use syntax:

type ::= <nonArrayType> | <arrayType>

arrayType ::= <nonArrayType> '[' ']'

nonArrayType ::= <tupleType> | <unionType> | <compoundType>
| <enumType> | <rangeType> | <patternType>
| <primaryType> | <simpleType> | <specialType>

tupleType ::= '[' <elementType1> [','] <elementType2> .. <elementTypeN> ']'
elementType ::= <type>

unionType ::= '(' <alternativeType1> '|' <alternativeType2 > '|' .. <alternativeTypeN> ')'
alternativeType ::= <type>

enumType ::= 'enum' '(' <enumValue1> '|' <enumValue2> '|' ... <enumValueN> ')'
enumValue ::= ( <identifier> | <quoted-string> | <dquoted-string> ) [ '=' <integer-constant> ]

rangeType ::= 'range' '(' <baseType> ':' <minValue> '..' <maxValue> ')'
minValue ::= <constant>
maxValue ::= <constant>

subsetType ::= 'subset' '(' <baseType> ':' <range1> [',' <range2>]... ')'
range ::= <minValue> '..' <maxValue> | <constant>

patternType ::= 'String' '(' <patternConstraint> [ ',' <patternConstraint> ]... ')'
patternConstraint ::= 'match:' <stringConstant>
| 'regex:' <stringConstant>
| 'minLength:' <integerConstant>
| 'maxLength:' <stringConstant>

compoundType ::= '{' <fieldSpec1> <fieldSpec2> ... <fieldSpecN> '}'

fieldSpec ::= <fieldIdentifier> ':' <fieldType> [ '=' <defaultValue> ] [';']
fieldType ::= <type>

primaryType ::= '<' <BuiltIn-Classname> '>'
BuiltIn-Classname ::= <identifier>

simpleType ::= <anyType> | <templateType> | <constraintTemplateType> | <namedType>

anyType ::= '*'

templateType ::= '#' <templateIdentifier>

constraintTemplateType ::= '#' <templateIdentifier> <setOfConstraintTypes>
setOfConstraintTypes ::= <unionType>

<namedType> ::= 'any' | 'struct' | <typeName_in_project> | <Smalltalk-Classname>
typeName_in_project ::= <identifier>

specialType ::= <monitorType> | <portType> | <datatypeType> | <performerType>

monitorType ::= 'monitor' '(' <baseType>')'

portType ::= 'port' '(' <baseType>')'

datatypeType ::= 'datatype' [ '(' <constraint> ')' ]

constraint ::= <primaryTypeName> |
'isUserDefinedType' | 'isWellKnownType' |
'isPrimaryType' |
'isNumberPrimaryType' | 'isCollectionPrimaryType' | 'isStreamPrimaryType'
'isArrayType' | 'isCTypeType'
'isCompoundType' | 'isEnumType' | 'isTupleType' | 'isUnionType'

performerType ::= 'performer' [ '(' interfaceSpec ')' ]

interfaceSpec ::= <identifier> |
'"' id-string '"'' |
'interface:' uuid

Notes: 
The separating commas in the tuple- and compound definitions are optional.
 This format is used if you select "Defined" type in the editor. It is also expected if you select "Define..." in one of the type menus (Pin-Type, Veriable-Type, Skill-Type).
Support for this representation is part of the base expecco system.

===DTD Type Definition===
A DTD definition can also be used to specify a compound type. For this, choose "''Compound (DTD-Defined)''", and paste the DTD into the text area.
Support for this representation is part of the base expecco system.

===C Language Type Definition===
A C language code fragment can also be used to specify a compound or union type. For this, choose "''CType (C-Defined)''", and paste the C type definition into the text area.
Instances of this type are especially useful when calling external DLL functions.
Support for this representation is part of the base expecco system.

A typical C language definition looks like:
/* C: */
struct {
int i1;
float f1;
double d1;
char c[20];
};
Notice, that the definition must begin with a "/* C: */" comment.

For more details, please refer to the [[ Datatype_Element/en#CTypes | Datatype - CTypes document ]].

===Enum Type Definition from C-define Directives===
An enum type can also be defined from a list of C-#define directives. These can be conveniently copy-pasted from a C-header file.
For this, choose "''Enum (from C-defines)''", and paste the defines into the text area.
Support for this representation is part of the base expecco system.

As an example, the following list of C-defines:

#define STATUS_OK 0
#define STATUS_ERR_CONNECT 1
#define STATUS_ERR_BROKEN 2

will generate the following enum type:

enum(STATUS_OK=0 , STATUS_ERR_CONNECT, STATUS_ERR_BROKEN)

The define values can be decimal integers, hex integers (0xXXXX), octal integers (0XXX) or binary integers (0bXXXX).

===XSD Type Definition===
A definition in XSD-XML. An XSD definition can also be used to specify a type.

This is an extension provided by a plugin. Please read the corresponding plugin documentation.

<usage: to be documented>

===COBOL Copybook Definition===
Parses a COBOL Copybook type-definition.

This is only available as plugin.
Please read the corresponding plugin documentation for details.

===ASN.1 Type Definiton===
Parses an ASN.1 type-definition.

This is only available as plugin. Please read the corresponding plugin documentation for details.

===Sun RPC IDL Type Definiton===
Parses a Sun RPC type-definition, which is used for example in the NFS file-system or in VISA lab equipment interfaces.
This is only available as plugin. Please read the corresponding plugin documentation for details.

===Microsoft COM/DCOM-IDL Type Definition===
Parses a COM/DCOM IDL type-definition.
This is only available as plugin. Please read the corresponding plugin documentation for details.

==See Also==
[[Datatype Element/en|Datatype Element]]


[[Category:Editors]] with more detail on primitive types and C-data types

Release Notes 25.x

2025-10-23T14:43:19Z

Sv:

See also: [[Release Notes 24.x]]
 

== Release 25.2 ==
*Improvement: Inspector shows XML Dom if it starts with '<' and ends with '>' and is parsable without error.
*Improvement: Handles very long index-lists (eg. 100k) more graceful
*Improvement: Bundled python3 installer updated to version 3.13.7
*Feature: Qt-Plugin supports Qt6.8 ([[QT_Testing/en#ExpeccoTestService_Library%3A_Delivery_in_Expecco_Versions|Delivered versions for QT and build environment]])
*Feature: groovy version 5.0.0 (needed for Java 25 and later)

== Release 25.1 ==
*Improvement: additional "Info" tab in inspector views
*Improvement: less memory usage in the activity log
*Improvement: better error messages and more links to settings from the activity log's error message
*Improvement: additional units and conversions in the [[PhysicalValues/en|physical values framework]]
*Improvement: more precision in the [[Numeric_Limits/en#Higher_Precision_Numbers|high precision trigonometric and math functions]]
*Improvement: WindowsAutomation: Plugin Update to FlaUI 5
*Improvement: Mobile Testing: Better Device Lock/Unlock Support
*Improvement: StandardLibrary: "File [ *CSV ]" blocks got an additional "characterEncoding" pin (useful for reading/writing e.g. utf-8 encoded CSV files)
*Improvement: ExcelLib: better documentation. Now requires the openpyxl package version >= 3.1.5.
*Improvement: better model language editor (translate and fetch-strings functions)
*Improvement: ODBCLibrary: improved compatibility with different database vendors (supports the CedarDB database)
*Feature: translate and spell check in the workspace window
*Feature: EditLock of suites loaded from expeccoALM / AIDYMO
*Feature: Start Test in expeccoALM / AIDYMO (via expecco)
*Feature: new library containing expeccoALM control actions (those from the AIDYMO menu)
*Fix: the version diff viewer (did not correctly copy changed attachment files)

Installing additional Frameworks/en

2025-09-12T14:20:03Z

Sv: /* Iron Python Installation */

== Introduction ==
If you intent to execute actions written for Java, Node, Python, .NET, C etc.,
or to test Java-, Windows- or mobile applications, additional frameworks have to be installed on your machine.

Mostly for legal reasons, but also because you will probably want to install a most up-to-date version, we do not bundle those with the expecco installation (except for a python setup, as noted below).

Please make sure that any required framework is installed, and the commands are found by expecco.

If they are already installed, but expecco fails to execute one of them, take a look at the PATH setting and/or the expecco "''Extras''" → "''Settings''" → "''Execution''" → "''External Script Interpreters''" settings. There, click on buttons labeled "?" to verify the installed version(s).

However, the recommendend setup is to only specify the command name in the settings, and ensure that the PATH variable is set correctly, to let expecco find the command via the PATH.
 The PATH should be set in your ".login" (Unix) or "autoexec.bat" (Windows) file accordingly.

== Required Frameworks Overview ==

{| class="wikitable"
|-
! Feature !! Required Framework(s)
|-
| Java/Groovy Actions || JRE (Java Runtime Environment) or: JDK (recommended)
|-
| NodeJS Actions || node
|-
| Python Actions || Python3.x (recommended) or: Python2.x (for older Python code)
|-
| Jython Actions || Java JRE (Java Runtime Environment) or JDK and Jython
|-
| Iron Python Actions || .NET CLR or: Mono (on non-Windows systems)
|-
| Ruby Actions || ruby
|-
| Java GUI Automation || JRE (Java Runtime Environment) or: JDK (recommended)
|-
| Windows GUI Automation || .NET CLR
|-
| WebTest (Selenium Webdriver) || JRE (Java Runtime Environment) webDrivers matching your web-browser version
|-
| Mobile Test (Appium) || JRE (Java Runtime Environment)
|-
| Bridged C Actions || C compiler toolchain (GCC, Clang, VisualC, Mingw or Borland)
|-
| Octave (Matlab scripts) || GNU Octave or a real Matlab
|-
| OCR (VNC, Screen Automation) || Tesseract language specific tessdata files
|-
| Vector/Canoe Plugin || .NET CLR
|-
| OPC Library || Python3 + opcua package
|}

== <div id="Java_Installation">Java Installation</div> (for Groovy Actions, Web- and Mobile Testing) ==
You can either install a plain Java Runtime Environment (JRE) or a full Java Development Kit (JDK). If only a JRE is installed, some functions will not work,
and we therefore recommend a JDK to be installed - typically at its standard location, "<CODE>C:\Program Files\Java\jdk-xxx</CODE>" (Windows), so it will run out of the box.
Expecco will try to figure out if and where Java was installed, but it it also possible to specify explicit pathes via the settings dialog.

Notice, that due to changed regulations by Oracle (i.e. legal restrictions), we may no longer provide a Java installation bundled with expecco;
you should navigate to the Oracle (or OpenJDK) website and install it from there.

Also notice, that on most systems, a Java is already installed, but it may be a runtime environment only.
Please verify, that a JDK is installed for the full set of features.

The expecco installation does include some required jar files (eg. groovy.jar, selenium jars and drivers etc.), but you may want to verify that they are the most up-to-date versions.

==== Selenium WebDriver ====
Especially the Selenium drivers (which are used to remote-control a Webbrowser when testing or automating graphical user interfaces in a browser) depend on the concrete browser version (i.e. Chrome version, Firefox version, etc.). Older drivers do not always work with a newer browser.

The deployed installation package includes a number of drivers for versions which were in use at that time, but especially due to automatic updates, these may be outdated on your machine. Please follow the instructions given by expecco and/or read [[Selenium_WebDriver_Plugin/en#Update_WebDriver|"Update WebDriver"]] when it encounters a problem.
 The GUIBrowser's connect dialog will check for version compatibility and offer an update function if required.

== <div id="DOTNET_Installation">.NET Installation</div> (for the .NET bridge, Windows Apps, IronPython Actions and some Plugins 1) ==

On Windows, a .NET framework is usually already installed.
 On Unix/Linux systems, you can install "Mono", which may provide enough functionality for your needs.
 Be aware, that some functions - especially GUI functions - may not be present or may not work perfectly (if at all) under Mono.

Mono can be downloaded from [https://www.mono-project.com/download/stable/ the Mono project web site].

1) for example, the Vector/Canoe plugin requires .NET (among others).

== <div id="Node_Installation">Node Installation</div> (for Node.js Actions) ==

Goto [ https://nodejs.org/en ] or [ https://nodejs.org/de/download/ ] and select the appropriate package for your machine.
When asked if additional packages are to be downloaded, answer "yes".
(Under Windows, VisualStudio build tools will then also be installed, in case any node module needs to be compiled from C/C++ code).

Open the node interpreter settings ("''Extras''" → "''Settings''" → "''Execution''" → "''External Script Interpreters''" → "''Node''") and verify that the "node" command is found along your PATH variable settings by clicking on the "?"-button. If found, its version should be shown.

If not found, either restart expecco (if you installed node while expecco was active), or enter the path to your node interpreter into the path field. You may even have to restart your cmd/shell session, in case the old shell environment does not contain the path to the new installed node.

== <div id="Python_Installation">Python Installation</div> (for Python Actions) ==

Expecco is delivered with an installation package for a relatively new Python version (currently Python 3.11.6 (expecco 23.2)), but of course, new versions are constantly released and the included Python might be outdated. You can (and probably should) download other versions [ https://www.python.org/downloads/ ].
Notice, that there are both packages for python3.x and python2.7 available, and you may have to install both, depending on the Python code to be executed later (although python2 is more and more becoming obsolete, there may still be frameworks for that old version to be found and used).

You can start by installing a Python3.x version only.
By the time of writing this document, the most recent Python version is 3.12, but expecco is known to work with older versions.
Be aware, that there are syntactic differences between Python2.x and Python3.x; for example "print ..." is a statement in 2.x whereas "print(...)" is a function call in 3.x.

Open the Python interpreter settings ("''Extras''" → "''Settings''" → "''Execution''" → "''External Script Interpreters''" → "''Python''") and verify that the "python" command is found along your PATH variable settings (click on "?").

[[Bild:PythonSettings.png|700px|PythonSettings]]

=== Python Commands ===

Notice, that there are 3 command fields, which can be set:
* Python Cmd Path
:is used if no explicit version is specified in a python action
* Python3 Cmd Path
:is used if the python action explicitly asks for python3
* Python2 Cmd Path
:is used if the python action explicitly asks for python2

Be aware and reminded, that these are different python interpreter instances: you cannot run both Python2 and Python3 code within the same python interpreter instance.

If not found, either restart expecco (if you installed Python while expecco was active), or enter the full path to your Python interpreter into the path field.

Make sure that the correct Python version is displayed (2.x vs. 3.x) when you click on the "?" button.

==== Default cmd paths ====

If no command is specified for one of the Python versions, expecco determines a default path, which is displayed in gray in the corresponding cmd path field.

The following sequence is used until a set cmd path is found:

*Python-Cmd is empty:
: ''Python3-Cmd-Path'' → ''Python2-Cmd-Path'' → ''Windows registry entry for Python3'' → ''Windows registry entry for Python2'' → "''python''"

* Python3-Cmd is empty:
: ''Python-Cmd-Path'' → ''Windows registry entry for Python3'' → "''python3''"

* Python2-Cmd is empty:
: '' Python cmd path'' → ''Windows registry entry for Python2'' → "''python2''"

You can display the effective Python version by clicking on the "?"-button.

=== Debugging python code ===

==== Debugging in expecco ====
To make your life easier, install a Python debugger; either:
pip install debugpy
or
pip install ptvsd
(they are more or less interchangeable, but "<code>ptvsd</code>" is outdated (no longer maintained) and replaced by the newer "<code>debugpy</code>")

Without a Python debugger, breakpoints cannot be placed in bridged Python code,
and you will not get a debugger on Python exceptions
(you should then see a warning and hint to install "debugpy" on the Transcript and in the info area).

To ensure that the breakpoints are observed, please uncheck the "Disable debugger" checkbox.

=====Problems with debugging=====

======Debugger does not start======

If the path for Python is specified with the variables "''%ProgramFiles%''" or "''%ProgramFiles(x86)%''", debugpy does not start.

Python: failed to enable PythonDebugger on port ..: [WinError 2] the system cannot find the file specified.

The remedy is to use the specific path such as "''C:\Program Files''" or "''C:\Program Files (x86)''".

======Warnings in output======

Debugger warning: It seems that frozen modules are being used, which may
make the debugger miss breakpoints. Please pass -Xfrozen_modules=off
to python to disable frozen modules.
Note: Debugging will proceed. Set PYDEVD_DISABLE_FILE_VALIDATION=1 to disable this validation.

In Python 3.11, the core modules essential for Python startup are “frozen”. ...
This reduces the steps in module execution process. Interpreter startup is now 10-15% faster
in Python 3.11. This has a big impact for short-running programs using Python.

It's not possible for the debugger to debug frozen modules as the filename is definitely required to hit breakpoints.

To deactivate the warning, set the environment variable PYDEVD_DISABLE_FILE_VALIDATION to 1, as described in the warning. Notice that the bridge needs to be restarted for the environment variable change to be effective (and possibly even expecco, unless you have specified that variable in "''Extras''" → "''Settings''" → "''External Script Interpreters''" → "''Environment Variables''")

==== Debugging in an external IDE ====
For more in depth debugging, you can run the Python bridge in an external IDE (like PyCharm) and use the debug features of the IDE.

For this, you should save the Python bridge code to a file or copy it to the clipboard using the "''Copy / Save Bridge Code...''" button.
Then open this python file in the IDE, and start in debug mode.

The Expecco Python blocks are called in the line:
result = actionFn(actionArgs, actionOutPins)

You can then step into the block code with a breakpoint at these lines.

In order for Expecco to connect to this Python bridge (instead of starting a new one),
you must first tick the checkbox "''Connect to already running bridge''" and terminate any previously running Python bridges (via "''Extras''" → "''Debugging''" → "''Shutdown all Bridge Connections''").

=== pip2 vs. pip3 vs. pip ===
To install Python packages, use the "<Code>pip</Code>" command. However, this command is usually a symbolic link to either "<Code>pip2</Code>" or "<Code>pip3</Code>".

You should use "<Code>pip3</Code>" to install packages for python3, and "<Code>pip2</Code>" for python2. Thus, it is safer to use one of those or "<Code>python3 -m pip install ...</Code>" instead of "<Code>pip install ...</Code>" to ensure that the module is installed for the current version.

On some systems, no pip2 command is present by default (and installing python3 will define the "<Code>pip</Code>" command as an alias to "<Code>pip3</Code>".

To get "pip2" on those systems, execute (on the command line):
wget https://bootstrap.pypa.io/get-pip.py
python2.7 get-pip.py

Things become even more confusing, if you have multiple python versions installed (for example, python3.7 and python3.9). Then, it is best invoke pip via the python command itself, eg. with: "<code>python3.7 -m pip install ...</code>".

=== Getting pip ===
Some Python installers seem to not install pip (at least it happened to us once, that "pip" was not found after a python installation).
 If "python -m pip" gives a warning, do the following:
* download "https://bootstrap.pypa.io/get-pip.py" (use "Save As" in a web browser, and save it to the desktop)
* open a cmd/shell window in that folder.
* execute "python get-pip.py"

== Jython Installation ==
Jython is a Python interpreter which runs inside a Java virtual machine, and thus has direct access to Java classes and objects. 
As a prerequisite, Java needs to be installed on your machine. Then goto [ https://www.jython.org/download.html ], download the Jython installer and run it (choose "standard install" or "full install").
 Remember the target directory. The jython command will be found there.
 If the "jython" command is not in your PATH, enter its full path in the "''Extras''" → "''Settings''" → "''Execution''" → "''External Script Interpreters''" → "''Jython''" settings dialog.
 However, it is usually better to add the path to your PATH variable (eg. as setup in the Windows environment settings, autoexec.bat or Unix's login.rc), and just give "jython".
 Notice that previous Jython versions were 2.x Pythons, which will sooner or later become outdated. It is recommended to download or upgrade to a 3.x version (if your code is 3.x compatible).

== Iron Python Installation ==
IronPython is a Python interpreter which runs inside the Common Language Runtime system, and thus has direct access to C# classes (and of yourse all other objects which live inside the CLR world). 
As a prerequisite, you'll need a .NET CLR (common language runtime) or mono (on Unix systems). On Windows systems, a reasonable CLR Version is usually already installed.
 Then go to [ https://ironpython.net/download ] or [ https://github.com/IronLanguages/ironpython3 ] and follow the instructions.

After the download, IronPython is typically installed in "<Code>C:\Program Files\IronPython 3.x</Code>", and you should enter the path "<Code>C:\Program Files\IronPython x.y\ipy.exe</Code>" into the IronPython command path field in the python settings dialog (or simply "ipy", if it is in your PATH).
Notice that previous IronPython versions were 2.x Pythons, which became obsolete. It is therefore recommended to download or upgrade to a 3.x version (if your code is 3.x compatible).

== Ruby Installation ==
Goto [ https://rubyinstaller.org/downloads ] and install ruby.
Then make sure that ruby is in your PATH setting or set the path to the command in the "''Extras''" → "''Settings''" → "''Execution''" → "''External Language Interpreters''" → "''Ruby''" settings. Typically it will look like "C:\Ruby32-x64\bin\ruby.exe" on windows.
 Create a new Ruby action and execute it to see if it works.

== Julia Installation ==
Goto [ https://julialang.org/downloads] and install.
Then make sure that julia is in your PATH setting or set the path to the command in the "''Extras''" → "''Settings''" → "''Execution''" → "''External Language Interpreters''" → "''Other''" settings. Typically it will look like "%LOCALAPPDATA%\Programs\Julia-1.10.4\bin\julia.exe" on windows.
 Create a new Julia action and execute it to see if it works.

== C Compiler Toolchain Installation (for C-Actions) ==

For a quick verify if the setup is working, create a new (default) bridged C action and execute it (it should generate a "Hello World" message).

==== C Compiler Toolchain Installation ====

You need a C-compiler toolchain to be installed for C-coded actions.
* On Unix/Linux systems, these are usually already present on the machine (try "<Code>cc --version</Code>" in a shell window; if you get a reasonable response, you are usually ready to go).
* On Windows, install one of "Borland", "VisualC", "VisualC Redistributable" or "MingGW". We recommend MingGW.
* On OSX, you have to install "XCode" or the "Command Line Tools" subset.

===== Windows + Borland (32bit) =====
* get the free Borland command line tools (see https://borland-c.software.informer.com/5.5) and install them (typically, under "C:\borland\bcc55")
* ensure that the link.cfg and bcc55.cfg files are present in the "C:\borland\bcc55\bin" directory.
* verify the installation by typing "bcc32". A help message should appear.
* in the expecco settings, goto "''Execution''" → "''External Script Interpreters''" → "''CBridge''" and select the appropriate CC-Script ("compile_windows_bcc.bat"), which tells the bridge how to compile the C-action code (more below).

===== Windows + Visual-C (32 or 64bit) =====
* similar to above, check for the "cl" command.
* in the expecco settings, goto "''Execution''" → "''External Script Interpreters''" → "''CBridge''" and select the appropriate CC-Script ("compile_windows_vc32.bat", "compile_windows_vc64.bat" or "compile_windows_vc64_redist.bat"); see below.

===== Windows + Mingw (32 or 64bit) =====
* get the mingw64 compiler and install it (best is under "c:\mingw64" or "c:\program files\mingw64").
* verify the installation by typing "gcc --help".
* in the expecco settings, goto "''Execution''" → "''External Script Interpreters''" → "''CBridge''" and select the appropriate CC-Script ("compile_windows_mingw32.bat" or "compile_windows_mingw64.bat"); see below.

When a C-coded action is about to be executed, its C-code will be compiled ''just in time'' using that toolchain. For that, the cBridge executes a configurable batch or shell script. For some commonly used toolchains, corresponding scripts are provided, but you can or may have to add your own script(s), in case you need special compile options, additional link library options or if you want to compile with a compiler not supported by the standard installation (eg. Intel compilers).

If you get compilation errors, take a look at the "compile_xxx" scripts in "<code>packages/exept/expecco/bridgeFramework/cBridge/cLibrary</code>" under the expecco installation folder.

If required, add your own script to call whatever compiler you need, and select it in the cBridge settings dialog
("''Extras''" → "''Settings''" → "''Execution''" → "''External Language Interpreters''" → "''CBridge''"). You must also add your own script, if special compiler flags or additional standard pathes are to be setup.

Notice, that we currently do not provide compilation scripts for C++; however, by declaring entry-functions (extern "C") in your C++ code, these can be called from C.

If no toolchain is installed, you can still see and edit C-code actions, but obviously not execute them.

===== Windows + Mingw32 =====
Same as above; recommended installation directories are "c:\mingw32" or "c:\program files\mingw32"

==== C Compiler Toolchain at Test-Execution Time ====
You can tell expecco to embed a pre-compiled object file into the saved ".ets" suite file ("''Store Object Files in Project''" checkbox in the CBridge settings dialog). If checked, C-Bridge actions will be compiled by your current session (using the configured toolchain) and the generated object file(s) will be saved with the suite. When the suite is later executed, no compiler toolchain will be needed on the test machine. Make sure that all required C actions are executed at least once.

Expecco does not include cross compilation support; that means, that only object files for the current architecture can be generated. However, if you load the suite into another architecture's expecco, additional object files for that other architecture will be generated and added to the ".ets" when saved. So afterwards, object files for both architectures will be present in the ets.

To summarize, if you want to deploy a library with embedded C-actions, which will have to be executed on (say) both a Linux and a Windows machine, where both test-execution machines have no compiler toolchain installed, perform the following steps:
# load the suite on a Linux machine (with C-compiler toolchain available)
# ensure that the "''Store Object Files''" flag is checked.
# Save the suite
# load the saved ".ets" on a Windows machine (with C-toolchain available)
# Save it again.
The last saved ".ets" will now contain object files for both architectures.
Be aware, that you may have to repeat the steps for 32 and 64 bit architectures, if the suite is to be executed eventually on both.

Be reminded that this procedure is not needed, if the machine which executes the tests does have a C-toolchain installed. And especially, if it is the same as your development machine.

== <div id="Cling_Installation">Cling Installation</div> (for RootCling Actions) ==

Support for Cling is "''work in progress''" and currently considered an "''experimental''" feature which is not available/enabled in the current deployed version.

Cling (aka "Root Cling") is a dynamic language system for C/C++.
Code can be entered in C++, which is dynamically (just in time) compiled to fast machine code.

Cling can be downloaded from the [https://root.cern/cling Cern web site] and/or installed via a package installer:

;Linux:
: -- see https://root.cern/download/cling/ --
Download one of the tar archives and unpack the files into some folder (such as "/opt/cling").

;Windows
: Sorry, to our knowledge, there exists no ready-to-install version for Windows at the time of writing this document.

;OS X(Mac):
: <code>brew install cling</code>

Depending on whether cling is found along your path, or you want to select a particular version,
specify the cling installation folder in the cling settings dialog "''Extras''" → "''Settings''" → "''Execution''" → "''External Language Interpreters''" → "''Cling''".
 There, click on the "?" button to verify that cling is found.

== Smalltalk Installation ==

Support for bridged Smalltalk is "''work in progress''", currently disabled and is planned for a future version.
However, scripted Smalltalk is already available.

== Scheme Installation ==

Support for bridged Scheme is "''work in progress''", currently disabled and is planned for a future version.
However, scripted Scheme is already available.

You can configure expecco to either use any standard scheme interpreter (whichever is installed as "scheme" command),
or to use an explicit implementation. Currently, supported are ChezScheme, ChickenScheme and Racket/MZScheme.

=== Chicken Scheme ===

[https://code.call-cc.org Chicken] can be compiled from [https://code.call-cc.org source] or installed via a package manager.

;Windows:
: https://chocolatey.org/packages/chicken/
: or:
: see https://wiki.call-cc.org/platforms#microsoft-windows-

;Linux:
: see https://wiki.call-cc.org/platforms#linux

;OS X (mac):
: brew install chicken
: or:
: see https://wiki.call-cc.org/platforms#mac-os-x

=== Chez Scheme ===

See [ https://github.com/cisco/ChezScheme ] for instructions.

A Windows binary and sources of release 9.5.4 are found at [ https://github.com/cisco/ChezScheme/releases/tag/v9.5.4 ].

== <div id="GnuPlot_Installation">GnuPlot Installation</div> (for Graph Attachments to the Report) ==

Gnuplot makes it easy to add graphs for measurement data or statistics to the
report and/or to create attachments for them.
To install gnuplot execute (in a terminal):

;Linux:
: -- to be determined and documented --
: please refer to the official Gnuplot website: http://www.gnuplot.info/download.html

;Windows:
: -- to be determined and documented --
: please refer to the official Gnuplot website: http://www.gnuplot.info/download.html

;OS X (Mac):
: <code>brew install gnuplot</code>
: or download a binary package eg. from:
:  https://csml-wiki.northwestern.edu/index.php/Binary_versions_of_Gnuplot_for_OS_X

== <div id="GNU_Octave_Installation">GNU Octave Installation</div> (Matlab compatible Scripting) ==

;OS X (Mac):
: Download a dmg from
:  https://wiki.octave.org/Octave_for_macOS
: or:
:  https://octave-app.org
: or:
: <code>sudo port install octave</code>

;Windows:
:Download from https://www.gnu.org/software/octave/download.

Warning: octave is huge (roughly 1Gb download).
 Also notice: octave needs gnuplot to generate image files from graphs.

If you are already using Matlab, set the path to the matlab executable in the "''Execution''" → [[Settings ExternalToolsSettings/en#GnuOctave_Path | "''External Script Interpreter''"]] settings.

==Dart Installation==
Goto [https://dart.dev/get-dart dart.dev] and follow the instructions there.

==R Installation==
Goto [https://www.r-project.org/ www.r-project.org] and follow the instructions there.
 OpenSuse users can "<code>zypper install R-base R-base-devel</code>".

== Go ==
For downloads, go to [https://go.dev/dl/ https://go.dev/dl/].
 OpenSuse users can "<code>zypper install go-devel</code>".

Make sure that go is in your PATH or else define the full pathname to go in the "''Execution''" → "''External Script Interpreters'' "→ "''Others''" settings dialog.

== TCL, and all the others ==
If you use those, you probably know how to install and update them.
Follow the usual installation instructions and - unless the interpreter is found along your PATH setting, define the path in the expecco "''Execution''" → "''External Script Interpreters'' "→ "''Others''" settings dialog.

== <div id="OCR">OCR</div> (Optical Character Recognition) ==
In order to extract text from bitmap images,
an OCR framework is needed. It is also needed if you want to automate the local screen or a VNC screen AND you need to extract text or numeric values from it.

Both open source and commercial frameworks can be found and used.
Good results are achieved by the free (and open source) "Tesseract" framework,
which we recommended, unless you already have a more powerful non-free commercial OCR framework at hand
(although supported, we do NOT recommend capture2Text or GNU-ocrad; they do not provide detailed per-word information and/or delivered poor recognition results. At least at the time this document was written).

Tesseract is hosted at [ https://github.com/tesseract-ocr/tessdoc ] and can be downloaded from [ https://github.com/tesseract-ocr/tessdoc/blob/master/Downloads.md ].
 Follow the installation instructions there.

;Windows and OS X
:binaries are found at [ https://github.com/UB-Mannheim/tesseract/wiki ]

In order to recognize national language characters (eg. accents, diareses/Umlauts), you'll also need language specific Tesseract-Data files. Please also install those for German, French, etc. from [ https://github.com/tesseract-ocr/tessdata ].

== AI (Tensorflow) ==
These are typically used via Python actions, and installed using a Python package manager (pip). Please refer to Tensorflow web pages for details.

Installing additional Frameworks/en

2025-09-12T14:18:53Z

Sv: /* Jython Installation */

== Introduction ==
If you intent to execute actions written for Java, Node, Python, .NET, C etc.,
or to test Java-, Windows- or mobile applications, additional frameworks have to be installed on your machine.

Mostly for legal reasons, but also because you will probably want to install a most up-to-date version, we do not bundle those with the expecco installation (except for a python setup, as noted below).

Please make sure that any required framework is installed, and the commands are found by expecco.

If they are already installed, but expecco fails to execute one of them, take a look at the PATH setting and/or the expecco "''Extras''" → "''Settings''" → "''Execution''" → "''External Script Interpreters''" settings. There, click on buttons labeled "?" to verify the installed version(s).

However, the recommendend setup is to only specify the command name in the settings, and ensure that the PATH variable is set correctly, to let expecco find the command via the PATH.
 The PATH should be set in your ".login" (Unix) or "autoexec.bat" (Windows) file accordingly.

== Required Frameworks Overview ==

{| class="wikitable"
|-
! Feature !! Required Framework(s)
|-
| Java/Groovy Actions || JRE (Java Runtime Environment) or: JDK (recommended)
|-
| NodeJS Actions || node
|-
| Python Actions || Python3.x (recommended) or: Python2.x (for older Python code)
|-
| Jython Actions || Java JRE (Java Runtime Environment) or JDK and Jython
|-
| Iron Python Actions || .NET CLR or: Mono (on non-Windows systems)
|-
| Ruby Actions || ruby
|-
| Java GUI Automation || JRE (Java Runtime Environment) or: JDK (recommended)
|-
| Windows GUI Automation || .NET CLR
|-
| WebTest (Selenium Webdriver) || JRE (Java Runtime Environment) webDrivers matching your web-browser version
|-
| Mobile Test (Appium) || JRE (Java Runtime Environment)
|-
| Bridged C Actions || C compiler toolchain (GCC, Clang, VisualC, Mingw or Borland)
|-
| Octave (Matlab scripts) || GNU Octave or a real Matlab
|-
| OCR (VNC, Screen Automation) || Tesseract language specific tessdata files
|-
| Vector/Canoe Plugin || .NET CLR
|-
| OPC Library || Python3 + opcua package
|}

== <div id="Java_Installation">Java Installation</div> (for Groovy Actions, Web- and Mobile Testing) ==
You can either install a plain Java Runtime Environment (JRE) or a full Java Development Kit (JDK). If only a JRE is installed, some functions will not work,
and we therefore recommend a JDK to be installed - typically at its standard location, "<CODE>C:\Program Files\Java\jdk-xxx</CODE>" (Windows), so it will run out of the box.
Expecco will try to figure out if and where Java was installed, but it it also possible to specify explicit pathes via the settings dialog.

Notice, that due to changed regulations by Oracle (i.e. legal restrictions), we may no longer provide a Java installation bundled with expecco;
you should navigate to the Oracle (or OpenJDK) website and install it from there.

Also notice, that on most systems, a Java is already installed, but it may be a runtime environment only.
Please verify, that a JDK is installed for the full set of features.

The expecco installation does include some required jar files (eg. groovy.jar, selenium jars and drivers etc.), but you may want to verify that they are the most up-to-date versions.

==== Selenium WebDriver ====
Especially the Selenium drivers (which are used to remote-control a Webbrowser when testing or automating graphical user interfaces in a browser) depend on the concrete browser version (i.e. Chrome version, Firefox version, etc.). Older drivers do not always work with a newer browser.

The deployed installation package includes a number of drivers for versions which were in use at that time, but especially due to automatic updates, these may be outdated on your machine. Please follow the instructions given by expecco and/or read [[Selenium_WebDriver_Plugin/en#Update_WebDriver|"Update WebDriver"]] when it encounters a problem.
 The GUIBrowser's connect dialog will check for version compatibility and offer an update function if required.

== <div id="DOTNET_Installation">.NET Installation</div> (for the .NET bridge, Windows Apps, IronPython Actions and some Plugins 1) ==

On Windows, a .NET framework is usually already installed.
 On Unix/Linux systems, you can install "Mono", which may provide enough functionality for your needs.
 Be aware, that some functions - especially GUI functions - may not be present or may not work perfectly (if at all) under Mono.

Mono can be downloaded from [https://www.mono-project.com/download/stable/ the Mono project web site].

1) for example, the Vector/Canoe plugin requires .NET (among others).

== <div id="Node_Installation">Node Installation</div> (for Node.js Actions) ==

Goto [ https://nodejs.org/en ] or [ https://nodejs.org/de/download/ ] and select the appropriate package for your machine.
When asked if additional packages are to be downloaded, answer "yes".
(Under Windows, VisualStudio build tools will then also be installed, in case any node module needs to be compiled from C/C++ code).

Open the node interpreter settings ("''Extras''" → "''Settings''" → "''Execution''" → "''External Script Interpreters''" → "''Node''") and verify that the "node" command is found along your PATH variable settings by clicking on the "?"-button. If found, its version should be shown.

If not found, either restart expecco (if you installed node while expecco was active), or enter the path to your node interpreter into the path field. You may even have to restart your cmd/shell session, in case the old shell environment does not contain the path to the new installed node.

== <div id="Python_Installation">Python Installation</div> (for Python Actions) ==

Expecco is delivered with an installation package for a relatively new Python version (currently Python 3.11.6 (expecco 23.2)), but of course, new versions are constantly released and the included Python might be outdated. You can (and probably should) download other versions [ https://www.python.org/downloads/ ].
Notice, that there are both packages for python3.x and python2.7 available, and you may have to install both, depending on the Python code to be executed later (although python2 is more and more becoming obsolete, there may still be frameworks for that old version to be found and used).

You can start by installing a Python3.x version only.
By the time of writing this document, the most recent Python version is 3.12, but expecco is known to work with older versions.
Be aware, that there are syntactic differences between Python2.x and Python3.x; for example "print ..." is a statement in 2.x whereas "print(...)" is a function call in 3.x.

Open the Python interpreter settings ("''Extras''" → "''Settings''" → "''Execution''" → "''External Script Interpreters''" → "''Python''") and verify that the "python" command is found along your PATH variable settings (click on "?").

[[Bild:PythonSettings.png|700px|PythonSettings]]

=== Python Commands ===

Notice, that there are 3 command fields, which can be set:
* Python Cmd Path
:is used if no explicit version is specified in a python action
* Python3 Cmd Path
:is used if the python action explicitly asks for python3
* Python2 Cmd Path
:is used if the python action explicitly asks for python2

Be aware and reminded, that these are different python interpreter instances: you cannot run both Python2 and Python3 code within the same python interpreter instance.

If not found, either restart expecco (if you installed Python while expecco was active), or enter the full path to your Python interpreter into the path field.

Make sure that the correct Python version is displayed (2.x vs. 3.x) when you click on the "?" button.

==== Default cmd paths ====

If no command is specified for one of the Python versions, expecco determines a default path, which is displayed in gray in the corresponding cmd path field.

The following sequence is used until a set cmd path is found:

*Python-Cmd is empty:
: ''Python3-Cmd-Path'' → ''Python2-Cmd-Path'' → ''Windows registry entry for Python3'' → ''Windows registry entry for Python2'' → "''python''"

* Python3-Cmd is empty:
: ''Python-Cmd-Path'' → ''Windows registry entry for Python3'' → "''python3''"

* Python2-Cmd is empty:
: '' Python cmd path'' → ''Windows registry entry for Python2'' → "''python2''"

You can display the effective Python version by clicking on the "?"-button.

=== Debugging python code ===

==== Debugging in expecco ====
To make your life easier, install a Python debugger; either:
pip install debugpy
or
pip install ptvsd
(they are more or less interchangeable, but "<code>ptvsd</code>" is outdated (no longer maintained) and replaced by the newer "<code>debugpy</code>")

Without a Python debugger, breakpoints cannot be placed in bridged Python code,
and you will not get a debugger on Python exceptions
(you should then see a warning and hint to install "debugpy" on the Transcript and in the info area).

To ensure that the breakpoints are observed, please uncheck the "Disable debugger" checkbox.

=====Problems with debugging=====

======Debugger does not start======

If the path for Python is specified with the variables "''%ProgramFiles%''" or "''%ProgramFiles(x86)%''", debugpy does not start.

Python: failed to enable PythonDebugger on port ..: [WinError 2] the system cannot find the file specified.

The remedy is to use the specific path such as "''C:\Program Files''" or "''C:\Program Files (x86)''".

======Warnings in output======

Debugger warning: It seems that frozen modules are being used, which may
make the debugger miss breakpoints. Please pass -Xfrozen_modules=off
to python to disable frozen modules.
Note: Debugging will proceed. Set PYDEVD_DISABLE_FILE_VALIDATION=1 to disable this validation.

In Python 3.11, the core modules essential for Python startup are “frozen”. ...
This reduces the steps in module execution process. Interpreter startup is now 10-15% faster
in Python 3.11. This has a big impact for short-running programs using Python.

It's not possible for the debugger to debug frozen modules as the filename is definitely required to hit breakpoints.

To deactivate the warning, set the environment variable PYDEVD_DISABLE_FILE_VALIDATION to 1, as described in the warning. Notice that the bridge needs to be restarted for the environment variable change to be effective (and possibly even expecco, unless you have specified that variable in "''Extras''" → "''Settings''" → "''External Script Interpreters''" → "''Environment Variables''")

==== Debugging in an external IDE ====
For more in depth debugging, you can run the Python bridge in an external IDE (like PyCharm) and use the debug features of the IDE.

For this, you should save the Python bridge code to a file or copy it to the clipboard using the "''Copy / Save Bridge Code...''" button.
Then open this python file in the IDE, and start in debug mode.

The Expecco Python blocks are called in the line:
result = actionFn(actionArgs, actionOutPins)

You can then step into the block code with a breakpoint at these lines.

In order for Expecco to connect to this Python bridge (instead of starting a new one),
you must first tick the checkbox "''Connect to already running bridge''" and terminate any previously running Python bridges (via "''Extras''" → "''Debugging''" → "''Shutdown all Bridge Connections''").

=== pip2 vs. pip3 vs. pip ===
To install Python packages, use the "<Code>pip</Code>" command. However, this command is usually a symbolic link to either "<Code>pip2</Code>" or "<Code>pip3</Code>".

You should use "<Code>pip3</Code>" to install packages for python3, and "<Code>pip2</Code>" for python2. Thus, it is safer to use one of those or "<Code>python3 -m pip install ...</Code>" instead of "<Code>pip install ...</Code>" to ensure that the module is installed for the current version.

On some systems, no pip2 command is present by default (and installing python3 will define the "<Code>pip</Code>" command as an alias to "<Code>pip3</Code>".

To get "pip2" on those systems, execute (on the command line):
wget https://bootstrap.pypa.io/get-pip.py
python2.7 get-pip.py

Things become even more confusing, if you have multiple python versions installed (for example, python3.7 and python3.9). Then, it is best invoke pip via the python command itself, eg. with: "<code>python3.7 -m pip install ...</code>".

=== Getting pip ===
Some Python installers seem to not install pip (at least it happened to us once, that "pip" was not found after a python installation).
 If "python -m pip" gives a warning, do the following:
* download "https://bootstrap.pypa.io/get-pip.py" (use "Save As" in a web browser, and save it to the desktop)
* open a cmd/shell window in that folder.
* execute "python get-pip.py"

== Jython Installation ==
Jython is a Python interpreter which runs inside a Java virtual machine, and thus has direct access to Java classes and objects. 
As a prerequisite, Java needs to be installed on your machine. Then goto [ https://www.jython.org/download.html ], download the Jython installer and run it (choose "standard install" or "full install").
 Remember the target directory. The jython command will be found there.
 If the "jython" command is not in your PATH, enter its full path in the "''Extras''" → "''Settings''" → "''Execution''" → "''External Script Interpreters''" → "''Jython''" settings dialog.
 However, it is usually better to add the path to your PATH variable (eg. as setup in the Windows environment settings, autoexec.bat or Unix's login.rc), and just give "jython".
 Notice that previous Jython versions were 2.x Pythons, which will sooner or later become outdated. It is recommended to download or upgrade to a 3.x version (if your code is 3.x compatible).

== Iron Python Installation ==
JIronPython is a Python interbreter which runs inside the Common Language Runtime system, and thus has direct access to C# classes (and of yourse all other objects which live inside the CLR world). 
As a prerequisite, you'll need a .NET CLR (common language runtime) or mono (on Unix systems). On Windows systems, a reasonable CLR Version is usually already installed.
 Then go to [ https://ironpython.net/download ] or [ https://github.com/IronLanguages/ironpython3 ] and follow the instructions.

After the download, IronPython is typically installed in "<Code>C:\Program Files\IronPython 3.x</Code>", and you should enter the path "<Code>C:\Program Files\IronPython x.y\ipy.exe</Code>" into the IronPython command path field in the python settings dialog (or simply "ipy", if it is in your PATH).
Notice that previous IronPython versions were 2.x Pythons, which became obsolete. It is therefore recommended to download or upgrade to a 3.x version (if your code is 3.x compatible).

== Ruby Installation ==
Goto [ https://rubyinstaller.org/downloads ] and install ruby.
Then make sure that ruby is in your PATH setting or set the path to the command in the "''Extras''" → "''Settings''" → "''Execution''" → "''External Language Interpreters''" → "''Ruby''" settings. Typically it will look like "C:\Ruby32-x64\bin\ruby.exe" on windows.
 Create a new Ruby action and execute it to see if it works.

== Julia Installation ==
Goto [ https://julialang.org/downloads] and install.
Then make sure that julia is in your PATH setting or set the path to the command in the "''Extras''" → "''Settings''" → "''Execution''" → "''External Language Interpreters''" → "''Other''" settings. Typically it will look like "%LOCALAPPDATA%\Programs\Julia-1.10.4\bin\julia.exe" on windows.
 Create a new Julia action and execute it to see if it works.

== C Compiler Toolchain Installation (for C-Actions) ==

For a quick verify if the setup is working, create a new (default) bridged C action and execute it (it should generate a "Hello World" message).

==== C Compiler Toolchain Installation ====

You need a C-compiler toolchain to be installed for C-coded actions.
* On Unix/Linux systems, these are usually already present on the machine (try "<Code>cc --version</Code>" in a shell window; if you get a reasonable response, you are usually ready to go).
* On Windows, install one of "Borland", "VisualC", "VisualC Redistributable" or "MingGW". We recommend MingGW.
* On OSX, you have to install "XCode" or the "Command Line Tools" subset.

===== Windows + Borland (32bit) =====
* get the free Borland command line tools (see https://borland-c.software.informer.com/5.5) and install them (typically, under "C:\borland\bcc55")
* ensure that the link.cfg and bcc55.cfg files are present in the "C:\borland\bcc55\bin" directory.
* verify the installation by typing "bcc32". A help message should appear.
* in the expecco settings, goto "''Execution''" → "''External Script Interpreters''" → "''CBridge''" and select the appropriate CC-Script ("compile_windows_bcc.bat"), which tells the bridge how to compile the C-action code (more below).

===== Windows + Visual-C (32 or 64bit) =====
* similar to above, check for the "cl" command.
* in the expecco settings, goto "''Execution''" → "''External Script Interpreters''" → "''CBridge''" and select the appropriate CC-Script ("compile_windows_vc32.bat", "compile_windows_vc64.bat" or "compile_windows_vc64_redist.bat"); see below.

===== Windows + Mingw (32 or 64bit) =====
* get the mingw64 compiler and install it (best is under "c:\mingw64" or "c:\program files\mingw64").
* verify the installation by typing "gcc --help".
* in the expecco settings, goto "''Execution''" → "''External Script Interpreters''" → "''CBridge''" and select the appropriate CC-Script ("compile_windows_mingw32.bat" or "compile_windows_mingw64.bat"); see below.

When a C-coded action is about to be executed, its C-code will be compiled ''just in time'' using that toolchain. For that, the cBridge executes a configurable batch or shell script. For some commonly used toolchains, corresponding scripts are provided, but you can or may have to add your own script(s), in case you need special compile options, additional link library options or if you want to compile with a compiler not supported by the standard installation (eg. Intel compilers).

If you get compilation errors, take a look at the "compile_xxx" scripts in "<code>packages/exept/expecco/bridgeFramework/cBridge/cLibrary</code>" under the expecco installation folder.

If required, add your own script to call whatever compiler you need, and select it in the cBridge settings dialog
("''Extras''" → "''Settings''" → "''Execution''" → "''External Language Interpreters''" → "''CBridge''"). You must also add your own script, if special compiler flags or additional standard pathes are to be setup.

Notice, that we currently do not provide compilation scripts for C++; however, by declaring entry-functions (extern "C") in your C++ code, these can be called from C.

If no toolchain is installed, you can still see and edit C-code actions, but obviously not execute them.

===== Windows + Mingw32 =====
Same as above; recommended installation directories are "c:\mingw32" or "c:\program files\mingw32"

==== C Compiler Toolchain at Test-Execution Time ====
You can tell expecco to embed a pre-compiled object file into the saved ".ets" suite file ("''Store Object Files in Project''" checkbox in the CBridge settings dialog). If checked, C-Bridge actions will be compiled by your current session (using the configured toolchain) and the generated object file(s) will be saved with the suite. When the suite is later executed, no compiler toolchain will be needed on the test machine. Make sure that all required C actions are executed at least once.

Expecco does not include cross compilation support; that means, that only object files for the current architecture can be generated. However, if you load the suite into another architecture's expecco, additional object files for that other architecture will be generated and added to the ".ets" when saved. So afterwards, object files for both architectures will be present in the ets.

To summarize, if you want to deploy a library with embedded C-actions, which will have to be executed on (say) both a Linux and a Windows machine, where both test-execution machines have no compiler toolchain installed, perform the following steps:
# load the suite on a Linux machine (with C-compiler toolchain available)
# ensure that the "''Store Object Files''" flag is checked.
# Save the suite
# load the saved ".ets" on a Windows machine (with C-toolchain available)
# Save it again.
The last saved ".ets" will now contain object files for both architectures.
Be aware, that you may have to repeat the steps for 32 and 64 bit architectures, if the suite is to be executed eventually on both.

Be reminded that this procedure is not needed, if the machine which executes the tests does have a C-toolchain installed. And especially, if it is the same as your development machine.

== <div id="Cling_Installation">Cling Installation</div> (for RootCling Actions) ==

Support for Cling is "''work in progress''" and currently considered an "''experimental''" feature which is not available/enabled in the current deployed version.

Cling (aka "Root Cling") is a dynamic language system for C/C++.
Code can be entered in C++, which is dynamically (just in time) compiled to fast machine code.

Cling can be downloaded from the [https://root.cern/cling Cern web site] and/or installed via a package installer:

;Linux:
: -- see https://root.cern/download/cling/ --
Download one of the tar archives and unpack the files into some folder (such as "/opt/cling").

;Windows
: Sorry, to our knowledge, there exists no ready-to-install version for Windows at the time of writing this document.

;OS X(Mac):
: <code>brew install cling</code>

Depending on whether cling is found along your path, or you want to select a particular version,
specify the cling installation folder in the cling settings dialog "''Extras''" → "''Settings''" → "''Execution''" → "''External Language Interpreters''" → "''Cling''".
 There, click on the "?" button to verify that cling is found.

== Smalltalk Installation ==

Support for bridged Smalltalk is "''work in progress''", currently disabled and is planned for a future version.
However, scripted Smalltalk is already available.

== Scheme Installation ==

Support for bridged Scheme is "''work in progress''", currently disabled and is planned for a future version.
However, scripted Scheme is already available.

You can configure expecco to either use any standard scheme interpreter (whichever is installed as "scheme" command),
or to use an explicit implementation. Currently, supported are ChezScheme, ChickenScheme and Racket/MZScheme.

=== Chicken Scheme ===

[https://code.call-cc.org Chicken] can be compiled from [https://code.call-cc.org source] or installed via a package manager.

;Windows:
: https://chocolatey.org/packages/chicken/
: or:
: see https://wiki.call-cc.org/platforms#microsoft-windows-

;Linux:
: see https://wiki.call-cc.org/platforms#linux

;OS X (mac):
: brew install chicken
: or:
: see https://wiki.call-cc.org/platforms#mac-os-x

=== Chez Scheme ===

See [ https://github.com/cisco/ChezScheme ] for instructions.

A Windows binary and sources of release 9.5.4 are found at [ https://github.com/cisco/ChezScheme/releases/tag/v9.5.4 ].

== <div id="GnuPlot_Installation">GnuPlot Installation</div> (for Graph Attachments to the Report) ==

Gnuplot makes it easy to add graphs for measurement data or statistics to the
report and/or to create attachments for them.
To install gnuplot execute (in a terminal):

;Linux:
: -- to be determined and documented --
: please refer to the official Gnuplot website: http://www.gnuplot.info/download.html

;Windows:
: -- to be determined and documented --
: please refer to the official Gnuplot website: http://www.gnuplot.info/download.html

;OS X (Mac):
: <code>brew install gnuplot</code>
: or download a binary package eg. from:
:  https://csml-wiki.northwestern.edu/index.php/Binary_versions_of_Gnuplot_for_OS_X

== <div id="GNU_Octave_Installation">GNU Octave Installation</div> (Matlab compatible Scripting) ==

;OS X (Mac):
: Download a dmg from
:  https://wiki.octave.org/Octave_for_macOS
: or:
:  https://octave-app.org
: or:
: <code>sudo port install octave</code>

;Windows:
:Download from https://www.gnu.org/software/octave/download.

Warning: octave is huge (roughly 1Gb download).
 Also notice: octave needs gnuplot to generate image files from graphs.

If you are already using Matlab, set the path to the matlab executable in the "''Execution''" → [[Settings ExternalToolsSettings/en#GnuOctave_Path | "''External Script Interpreter''"]] settings.

==Dart Installation==
Goto [https://dart.dev/get-dart dart.dev] and follow the instructions there.

==R Installation==
Goto [https://www.r-project.org/ www.r-project.org] and follow the instructions there.
 OpenSuse users can "<code>zypper install R-base R-base-devel</code>".

== Go ==
For downloads, go to [https://go.dev/dl/ https://go.dev/dl/].
 OpenSuse users can "<code>zypper install go-devel</code>".

Make sure that go is in your PATH or else define the full pathname to go in the "''Execution''" → "''External Script Interpreters'' "→ "''Others''" settings dialog.

== TCL, and all the others ==
If you use those, you probably know how to install and update them.
Follow the usual installation instructions and - unless the interpreter is found along your PATH setting, define the path in the expecco "''Execution''" → "''External Script Interpreters'' "→ "''Others''" settings dialog.

== <div id="OCR">OCR</div> (Optical Character Recognition) ==
In order to extract text from bitmap images,
an OCR framework is needed. It is also needed if you want to automate the local screen or a VNC screen AND you need to extract text or numeric values from it.

Both open source and commercial frameworks can be found and used.
Good results are achieved by the free (and open source) "Tesseract" framework,
which we recommended, unless you already have a more powerful non-free commercial OCR framework at hand
(although supported, we do NOT recommend capture2Text or GNU-ocrad; they do not provide detailed per-word information and/or delivered poor recognition results. At least at the time this document was written).

Tesseract is hosted at [ https://github.com/tesseract-ocr/tessdoc ] and can be downloaded from [ https://github.com/tesseract-ocr/tessdoc/blob/master/Downloads.md ].
 Follow the installation instructions there.

;Windows and OS X
:binaries are found at [ https://github.com/UB-Mannheim/tesseract/wiki ]

In order to recognize national language characters (eg. accents, diareses/Umlauts), you'll also need language specific Tesseract-Data files. Please also install those for German, French, etc. from [ https://github.com/tesseract-ocr/tessdata ].

== AI (Tensorflow) ==
These are typically used via Python actions, and installed using a Python package manager (pip). Please refer to Tensorflow web pages for details.

Release Notes 25.x

2025-09-11T14:07:44Z

Sv: /* Release 25.2 */

See also: [[Release Notes 24.x]]
 

== Release 25.2 ==
*Improvement: Inspector shows XML Dom if it starts with '<' and ends with '>' and is parsable without error.
*Improvement: Handles very long index-lists (eg. 100k) more graceful
*Improvement: Bundled python3 installer updated to version 3.13.7

== Release 25.1 ==
*Improvement: additional "Info" tab in inspector views
*Improvement: less memory usage in the activity log
*Improvement: better error messages and more links to settings from the activity log's error message
*Improvement: additional units and conversions in the [[PhysicalValues/en|physical values framework]]
*Improvement: more precision in the [[Numeric_Limits/en#Higher_Precision_Numbers|high precision trigonometric and math functions]]
*Improvement: WindowsAutomation: Plugin Update to FlaUI 5
*Improvement: Mobile Testing: Better Device Lock/Unlock Support
*Improvement: StandardLibrary: "File [ *CSV ]" blocks got an additional "characterEncoding" pin (useful for reading/writing e.g. utf-8 encoded CSV files)
*Improvement: ExcelLib: better documentation. Now requires the openpyxl package version >= 3.1.5.
*Improvement: better model language editor (translate and fetch-strings functions)
*Improvement: ODBCLibrary: improved compatibility with different database vendors (supports the CedarDB database)
*Feature: translate and spell check in the workspace window
*Feature: EditLock of suites loaded from expeccoALM / AIDYMO
*Feature: Start Test in expeccoALM / AIDYMO (via expecco)
*Feature: new library containing expeccoALM control actions (those from the AIDYMO menu)
*Fix: the version diff viewer (did not correctly copy changed attachment files)

Lizenzserver expecco ALM

2025-09-04T08:48:23Z

Sv: /* Installation */

==Übersicht==

Der expecco Lizenzserver dient der zentralen Verwaltung von expecco Lizenzen. Durch den Lizenzserver kann expecco auf verschiedenen Rechnern (sowohl Entwicklungs- als auch reine Testausführungsrechner) ohne Dongle und lokale Lizenzdatei auf allen erreichbaren Rechnern im Netz installiert und ausgeführt werden.

Lizenzen werden dabei von den expecco-Rechnern vom Lizenzserver angefordert, im Lizenzserver reserviert,
und nach der Sitzung bzw. Testlauf wieder zurückgegeben. Damit können mehr Nutzer (allerdings nicht gleichzeitig) mit expecco arbeiten als Lizenzen erworben wurden.

Lizenzen sind kryptographisch gesicherte Dateien, welche nur in Verbindung mit einem von eXept gelieferten Lizenzserver-Dongle gelesen bzw. genutzt werden können. Lizenzen sind Dongle-spezifisch. Es ist also nicht notwendig, Maßnahmen zum Schutz vor Diebstahl oder Kopieren von Lizenzdateien zu ergreifen. Allerdings ist ein Verlust des Dongles aus nahe liegenden Gründen zu vermeiden.

{{SEITENTITEL:Lizenzservice Installation}}

== Voraussetzungen ==
Wir empfehlen expecco ALM auf einem durchgehend verfügbaren Server mit Windows Server 2012 / Windows 10 oder höher zu installieren. Die Installation auf anderen Betriebssystemen (wie z.B. Linux) wäre bei Bedarf auch möglich. Ebenso ist die Installation in einer Cloud möglich, dort ist der Betrieb ohne Dongle möglich.

Damit expecco ALM flüssig arbeiten kann, werden folgende Hardware-Anforderungen an den Server gestellt:
 - ein "dezidierter" Prozessor mit mindestens 2 GHz
 - mindestens 1 GB Arbeitsspeicher (ausschließlich für expecco ALM)
 - mindestens 10 GB Festplattenspeicher (je nach Größe der Daten die expecco ALM verwalten soll)

Stellen Sie sicher, dass dieser Server für alle Clients erreichbar ist. Clients sind alle Rechner der expecco ALM Benutzer, Rechner die expecco ALM zur Testausführung dienen und Rechner mit "Floating" lizenziertem expecco. Bei Problemen bezüglich der Erreichbarkeit wenden Sie sich bitte an Ihren Netzwerkadministrator.

== Installation ==

Bitte halten Sie Ihre Lizenzdatei und ggfs. den Dongle für die Installation von expecco ALM bereit. 
Für die Installation in der Cloud benötigen Sie keinen Dongle; wir liefern dann eine Lizenzdatei, die an die MAC-Adresse des Servers gebunden ist. Falls sich der Server und damit dessen MAC-Adresse ändert, erhalten Sie eine neue angepasste Lizenzdatei von uns.

Ihre Lizenzdatei und eine Verknüpfung zum aktuellen expecco ALM Setup haben wir Ihnen per E-Mail zu kommen lassen. Der Installer hat folgenden Namen "expecco ALM 24.2.0 Setup.exe", wobei die Versionsnummer abweichen kann. Den Dongle haben wir per Post an Sie versendet (es sei denn Sie evaluieren expecco ALM oder nutzen die Cloud Variante mit der MAC-Adressen-Bindung).

Gehen Sie bitte wie folgt vor:
* Laden Sie den expecco ALM Installer auf dem Server, auf dem expecco ALM künftig laufen soll, herunter
* Legen Sie Ihre Lizenzdatei ebenfalls auf dem Server ab
* Verbinden Sie Ihren Dongle mit dem Server (Wenn Sie expecco ALM evaluieren oder die Cloud Variante mit der MAC-Adressen-Bindung nutzen, überspringen Sie diesen Schritt)
* Führen Sie den expecco ALM Installer ("expecco ALM ?.?.?.? Setup.exe" bzw. unter Linux "expecco ALM ?.?.?.? Setup.package") aus

Für Linux werden zusätzliche Pakete der Linux-Distribution benötigt. Diese sind [[Installation#Installation_von_expecco_auf_Linux|hier]] aufgeführt.

Nachdem der Installer erfolgreich ausgeführt wurde, läuft expecco ALM bereits als Service. Auf Ihrem Desktop wurde eine Verknüpfung zu expecco ALM angelegt. Es wurde auch ein Ordner für expecco ALM in Ihrem Startmenü erstellt. Dort können Sie unter "Konfiguration" den Port ändern (Standard ist Port 8081) oder über die "Logdatei" eventuelle Probleme feststellen.

[[Datei:InstallAlmLicense.png|mini|Anhang 1]]
Über die Verknüpfung auf Ihrem Desktop lässt sich expecco ALM mit Ihrem Standardbrowser öffnen. Es wird eine Seite zum Installieren Ihrer expecco ALM Lizenz angezeigt (Anhang 1). Über "Lizenzdatei installieren" können Sie Ihre Lizenzdatei (die Sie bereits auf dem Server abgelegt haben) auswählen. Nach dem expecco ALM Ihre Lizenzdatei akzeptiert hat, können Sie diese entfernen. Wenn bereits eine gültige Lizenz installiert ist, wird stattdessen die Anmeldeseite angezeigt. Falls es sich bei Ihnen um eine Erstinstallation handelt, können Sie sich mit Anmeldenamen "admin" und Kennwort "admin" anmelden.

Falls eine leere Seite oder eine Fehlerseite angezeigt wird, probieren Sie einen anderen Port aus und/oder schauen Sie in der Logdatei nach Fehlermeldungen.

== SSL-Verschlüsselung / Proxy-Server ==
expecco ALM unterstützt aktuell noch nicht direkt SSL-Verschlüsselung. Über einen Proxy-Server ist diese aber problemlos einzurichten, z.B. über einen Apache-Server. Falls auf ihrem Server weitere Webseiten gehostet werden, ist dies ja ohnehin erforderlich, da sich nicht mehrere Prozesse gleichzeitig an den Port 443 binden können.

Eine Apache2 VirtualHost-Konfiguration würde entsprechend so aussehen (angenommen expecco ALM läuft mit Port 8465 - erforderliche Anpassung für ihre Konfiguration fett):
<VirtualHost *:443>
ServerName expeccoalm.xyz.de
ServerAdmin webmaster@xyz.de

Include /etc/letsencrypt/ssl-xyz.de.conf

SSLProxyEngine On

RewriteEngine on
RewriteCond %{HTTP:Upgrade} =websocket [NC]
RewriteRule /(.*) ws://localhost:8465/$1 [P,L]
RewriteCond %{HTTP:Upgrade} !=websocket [NC]

ProxyPass / http://localhost:8465/ nocanon
ProxyPassReverse / http://localhost:8465/
</VirtualHost>

Die SSL-Parameter mit dem Pfaden zu Ihren Zertifkaten uns Schlüsseln würden in diesem Konfigurations-Beispiel in der Apache-globalen Datei /etc/letsencrypt/ssl-xyz.de.conf liegen.

== Hinweise zur Lizenzierung ==
Wenn Sie expecco ALM erworben haben, erhalten Sie einen Dongle und eine Lizenzdatei. Falls Sie expecco ALM evaluieren, erhalten Sie ausschließlich die Lizenzdatei. Die Lizenzdatei beinhaltet eine für Sie individuelle expecco ALM Lizenz. So sind zum Beispiel: Der Name Ihrer Firma, für Sie freigeschaltete Module oder die Gültigkeitsdauer in der Lizenz hinterlegt. Der Dongle muss (insofern Sie expecco ALM erworben haben) ständig mit dem Server, auf dem expecco ALM ausgeführt wird, verbunden sein. Falls Sie den Dongle während des Betriebs abziehen, wird expecco ALM seinen Dienst einstellen.

== Lizenz wechseln ==
[[Datei:ChangeAlmLicense.png|mini|Anhang 2]]
Falls Sie eine aktuelle expecco ALM Version haben, können Sie eine neue Lizenzdatei "expecco ALM Lizenz *.lic" über das Webinterface von expecco ALM einspielen. Betrachten Sie dazu den angehängten Screenshot (Anhang 2).

Fall Sie eine ältere expecco ALM Version haben, müssen Sie folgendermaßen vorgehen:
 - Da Sie expecco ALM später neustarten müssen, tätigen Sie entsprechende Vorsorgemaßnahmen (Bspw. Benutzer abmelden, Datenbank sichern usw.)
 - Melden Sie sich auf dem Computer, der expecco ALM betreibt an
 - Begeben Sie sich in folgendes Verzeichnis "C:\Windows\SysWOW64\config\systemprofile\AppData\Roaming\expecco_ALM" oder falls es sich um ein 32Bit Betriebssystem handelt "C:\Windows\system32\config\systemprofile\AppData\Roaming\expecco_ALM" und löschen Sie die Datei "expecco_ALM.lic"
 - Starten Sie den expecco ALM Service über den Windows-Service-Manager neu oder beenden Sie über den Windows-Task-Manager den Prozess "expecco_ALM.exe", in letzterem Fall wird der Windows-Service-Manager expecco ALM automatisch neustarten.
 - Nun können Sie das expecco ALM Webinterface aufrufen. Es wird eine Seite zum Installieren Ihrer expecco ALM Lizenz angezeigt (Anhang 1). Über "Lizenzdatei installieren" können Sie Ihre Lizenzdatei. auswählen. Nach dem expecco ALM Ihre Lizenzdatei akzeptiert hat, können Sie diese entfernen.

== Einbringen von expecco Floating-Lizenzen ==
Der Lizenzservice von expecco ALM vergibt verfügbare expecco Floating-Lizenzen aus einem bestimmten Pool. 
In diesen zunächst leeren Pool können von eXept erworbene expecco Floating-Lizenzen eingebracht werden.
 
Diese expecco Floating-Lizenzen erhalten Sie als Lizenzdatei(en) üblicherweise per E-Mail. 
Eine Lizenzdatei kann eine oder mehrere expecco Floating-Lizenzen auch für verschiedene Komponenten (Basissystem, Plugins und Erweiterungen) enthalten. 
Sie können auch jederzeit weitere expecco Floating-Lizenzen erwerben und in den Pool einbringen.
 
expecco Floating-Lizenzen werden immer spezifisch für eine expecco ALM Lizenz erstellt und sind nur mit dieser und deren Dongle nutzbar. 
Es ist also nicht notwendig solche Lizenzdateien unter Verschluss zu halten oder über eine sichere Verbindung auszutauschen. 
Allerdings sollten Sie den Dongle sicher aufbewahren bzw. Diebstahl vorbeugen.
 
Zur Einbringen einer expecco Floating-Lizenz öffnen Sie expecco ALM und melden Sie sich an. 
Jetzt navigieren Sie über die obere Hauptnavigationsleiste zum "Lizenzservice" Modul.
 
Sie befinden sich nun im Lizenzservice und Ihnen wird die Liste der installierten expecco Floating-Lizenzen angezeigt. 
Wechseln Sie zur Registerkarte "expecco Lizenzdateien". 
Navigieren Sie mithilfe des Navigationsmenüs auf der linken Seite zu "Hochladen/Upload". 
Hier können Sie nun durch ein einfaches Hochladen Ihrer expecco Floating-Lizenzen selbige in den Pool einbringen. 
In der zuvor genannte Liste werden nun die eben hochgeladenen expecco Floating-Lizenzen anzeigt. 
Diese sind von nun an auch von entfernten expecco Clients abrufbar. 
Sie können auch jederzeit weitere expecco Floating-Lizenzen erwerben und in den Pool einbringen.

== Lizenz Übersicht ==
Welche einzelnen expecco Floating-Lizenzen verfügbar oder vergeben sind, 
erfahren Sie indem Sie zur Registerkarte "expecco Lizenzen" wechseln. 
Insbesondere ist hieraus ersichtlich, welcher Rechner/Benutzer welche expecco Floating-Lizenz aktuell nutzt. 
Dies ist beispielsweise sinnvoll, wenn ein expecco Client seine Sitzung versehentlich nicht beendet hat, 
und andere Nutzer eine entsprechende Lizenz benötigen.

Installation

2025-09-04T08:38:38Z

Sv: /* Auslösen einer Floating-Lizenz */

[[Installation/en#Additional_Packages_and_Frameworks| English Version]]

== Installation von expecco auf Windows ==

Sie erhalten eine E-Mail mit dem Link zu der expecco-Installationsdatei. Die Installationsdatei hat z.B. den Namen:

* expeccoSetup64-23.1.0.50.exe -> für die expecco-Basisinstallation

wobei hier 23.1.0 der Versionsnummer von expecco entspricht und 50 der Build-Nummer ("23.1.0.50" entspricht hier der Version zum Zeitpunkt der Erstellung dieses Dokuments - Sie werden mit Sicherheit eine andere Versionsnummer sehen).

Bitte laden Sie das Installationsprogramm auf Ihren Rechner.

=== Windows SmartScreen / Blockierte Ausführung ===

Führen Sie das Installationsprogramm für die expecco-Basisinstallation aus (''expeccoSetup64-***.exe'').

Es kann vorkommen, dass Ihr Anti-Virus-Programm wie bspw. der [https://de.wikipedia.org/wiki/SmartScreen-Filter], die Installation blockiert. Dies ist bei neuen oder Vorab-expecco-Versionen vermutlich damit begründet, dass Ihr Anti-Virus-Programm unsere Software noch nicht gut genug kennt. Bitte stellen Sie in dem Fall sicher, dass die Installationsdatei ausschließlich aus einer der folgenden Quellen heruntergeladen wurde https://exept.de/*, https://download.exept.de/*, https://cloud.exept.de/*. Wenn Sie sich sicher sind, dass die Installationsdatei von uns stammt, können Sie ohne Bedenken die Blockierung Ihres Anti-Virus-Programms ignorieren. Unsere Installationsprogramme sind auch mit einem Zertifikat der eXept Software AG signiert.

Die Installationsdatei für expecco sowie die expecco Programme sind mit dem digitalen Zertifikat von eXept Software AG signiert.

Im Falle vom [https://de.wikipedia.org/wiki/SmartScreen-Filter], gehen Sie bitte auf "Weitere Informationen" und dann auf "Trotzdem ausführen".

[[Bild:Windows_SmartScreen.png|300px|Report Settings]] [[Bild:Windows_SmartScreen_Trozdem_ausführen.png|300px|Report Settings]]

Falls Sie ein anderes Anti-Virus-Programm haben, informieren Sie sich bitte wie man dort die Blockierung ignorieren oder die Installationsdatei als Ausnahme definieren kann.

Folgen Sie dabei dem Installationsassistenten.
Sie können hier das Laufwerk und das Verzeichnis angeben, unter dem expecco installiert werden soll.
Außerdem können Sie die Komponenten angeben, die Sie installieren wollen.

Falls Sie Plugins für expecco lizenziert haben, können Sie bei der Installation die entsprechenden expecco-Plugins auswählen.
Angeboten werden alle Plugins - auch solche für die Sie keine Lizenzen erworben haben.
Falls Sie nicht lizenzierte Plugins installieren, ist deren Funktion in expecco nicht verfügbar und entsprechende Menu-Einträge entweder unsichtbar oder ausgegraut.
 Installierte, aber nicht lizenzierte Plugins sind erst dann verfügbar, wenn die dazu passenden Lizenzen (nach-)installiert wurden.
Ansonsten belegen Sie nur Platz auf der Festplatte.
Weitere Plugins können auch jederzeit nachträglich installiert werden. Auch können auch weitere Lizenzen jederzeit später erworben werden.

Nach der Installation finden Sie auf Ihrem Desktop das expecco-Symbol.
Über dieses Symbol können Sie expecco nun starten.
Beim erstmaligen Ausführen, erscheint ein Fenster, in dem eine Lizenz verlangt wird.
Je nachdem, ob Sie eine Einzellizenz oder eine Floating-Lizenz (per Lizenzserver) nutzen, müssen Sie die Lizenz entsprechend nachfolgender Beschreibung installieren.

=== Automatische Installation von expecco via Commandline (Windows) ===

Sie können expecco über die Kommandozeile, via Batchdatei oder ähnlichem installieren. Führen Sie dazu expecco wie folgt aus:
expeccoSetup-x.x.exe /S
Das "/S" steht für "''Silent''" und expecco installiert sich ohne GUI und ohne Fragen zu stellen.
Sie können optional auch ein spezifisches Installationsverzeichnis angeben:
expeccoSetup-x.x.exe /S /D="C:\Program Files (x86)\exept"
Damit expecco nach der Installation direkt starten kann, muss sichergestellt werden, dass eine Lizenz auf dem Zielrechner vorhanden ist. Hierfür kommen folgende Varianten in Frage.

'''Lizenz aus lokaler Lizenzdatei und Dongle''': 
Stecken Sie den Dongle in den Zielrechner. Kopieren Sie Ihre Lizenzdatei in Ihr Benutzerverzeichnis bspw. "<code>C:\Users\IhrBenutzername\</code>" unter dem Namen "<code>.expeccoLicense</code>", sodass die Datei "<code>C:\Users\IhrBenutzername\.expeccoLicense</code>" Ihrer Lizenzdatei entspricht.

'''Lizenz vom Lizenzserver''':
Hier müssen zunächst eine "Template" Lizenzdatei und "Template" expecco Einstellungen-Datei erstellt werden. Sie benötigen dafür ein laufendes expecco, welches mit Ihrem Lizenzserver verbunden ist. Starten Sie dieses expecco und konfigurieren Sie unter "''Extras''" → "''Einstellungen''" → "''Lizenzinstallation''" → "''Lizenz vom Lizenzserver''" Ihre "Template" Lizenzdatei. Diese sollte alle Plugins, die auf dem Zielrechner für die automatisierte expecco Installation über Commandline benötigt werden, enthalten. Fordern Sie diese Lizenz vom Lizenzserver an. Setzen Sie den Haken "Lizenzserver nutzen" und drücken Sie anschließend "Sichern". expecco hat nun die benötigten Template Dateien unter "<code>C:\Users\IhrBenutzername\AppData\Roaming\expecco</code>" angelegt. Kopieren Sie die "<code>.expeccoPreferences</code>" und die "<code>expeccoLicenseServerLicense</code>" Datei vor der automatischen expecco Installation in das entsprechende Verzeichnis auf Ihrem Zielrechner. expecco kann somit direkt nach der automatischen Installation starten.

=== Autostart von expecco ===

Öffnen Sie dazu mit der <kbd>Windows-Taste</KBD> + <KBD>"R"</KBD> ein Ausführungs-Fenster. Geben Sie dort "shell:startup" ein. Danach öffnet sich der Autostart-Ordner. Kopieren Sie die expecco-Verknüpfung vom Desktop in diesen Ordner. Nun wird expecco, nachdem sich dieser Benutzer angemeldet hat, automatisch gestartet. Folgend können Sie konfigurieren, dass sich dieser Benutzer automatisch anmeldet, wenn der Rechner angeschaltet wird. Drücken Sie dazu erneut <KBD>Windows-Taste</KBD> + <KBD>"R"</KBD>. Geben Sie nun "netplwiz" ein. Es öffnet sich der Benutzerkonten-Dialog. In diesem können Sie den Haken "Benutzer müssen Benutzernamen und Kennwort eingeben" abwählen. Diese Einstellung gilt nur für das Anmelden nachdem der Rechner hochgefahren ist.

Übrigens können diverse Parameter auf der [[Command Line Options|expecco-Kommandozeile]] angegeben werden. Hier sind insbesondere die Optionen [[Command Line Options#Startup|"--licenseFile"]], [[Command Line Options#Startup|"--licenseServer"]] und [[Command Line Options#Startup|"--licenseServerPort"]] zu erwähnen.

=== expecco Einstellungen vordefinieren ===

Es kann in bestimmten Fällen Sinn machen, die expecco Einstellungen für neue Windows-Benutzerkonten vorzudefinieren.
Z.B. könnte man die Adresse des Lizenzserver und die benötigten Pluginlizenzen vordefinieren.
Dies hätte den Vorteil, dass neue Benutzer direkt mit expecco loslegen können.

Gehen Sie zum Vordefinieren der expecco Einstellungen für neue Windows-Benutzerkonten folgendermaßen vor:
* starten Sie expecco auf einem bereits vorhandenen Benutzerkonto (kann auch ein anderer Windows Rechner sein)
* stellen Sie dessen expecco Einstellungen ("''Extras''" → "''Einstellungen''") wie zur Vorlage gewünscht ein und speichern Sie über "''Sichern''"
* navigieren Sie zu dem Verzeichnis "C:\Users\{IhrBenutzer}\AppData\Roaming\expecco\" und kopieren Sie die 2 Dateien ".expeccoPreferences" und "expeccoLicenseServerLicense"
* begeben Sie sich zum Zielrechner und erstellen Sie einen Ordner "expecco" unter "C:\Users\Default\AppData\Roaming\"
* fügen Sie die 2 kopierten Dateien auf dem Zielrechner unter "C:\Users\Default\AppData\Roaming\expecco\" ein

Jetzt werden alle neuen Windows-Benutzerkonten diese Einstellungen als Ausgangseinstellungen verwenden. Sie können diese Einstellungen auch bereits existierenden Windows-Benutzerkonten zuweisen. Hierfür fügen Sie die 2 Dateien in die entsprechenden Benutzerverzeichnisse auf dem Zielrechner "C:\Users\{ExistierenderBenutzer}\AppData\Roaming\expecco\" ein.

ACHTUNG: damit werden alle bereits getätigen Einstellungen der Benutzer überschrieben.

=== Update Installation von expecco (Windows) ===

Wie bei der Erstinstallation erhalten eine E-Mail mit dem Link zu den neuen expecco-Installationsdateien.
Bitte laden Sie die Installationsprogramme herunter.
Bei der Ausführung des Basis-Installationsprogramms "<code>expeccoSetup-xxx.exe</code>" erkennt expecco, dass es bereits installiert ist, und zeigt einen Dialog an, in dem Sie um eine Bestätigung gebeten werden, dass die alte expecco-Version deinstalliert werden darf.
Bestätigen Sie bitte diesen Dialog. Die alte expecco-Version wird mit allen Plugins deinstalliert.
Ihre Einstellungen, Lizenzdateien und Ihre Testsuiten bleiben erhalten.
Anschließend wird die neue expecco-Version wie bei der Erstinstallation (s.o.) installiert.

=== Lizenz installieren ===

Beim erstmaligen Ausführen erscheint ein Fenster, in dem eine Lizenz verlangt wird. Je nachdem, ob Sie eine Einzellizenz oder eine Floating-Lizenz (per Lizenzserver) nutzen, können Sie die Lizenz konfigurieren.

[[#Konfiguration der Einzellizenz | Konfiguration der Einzellizenz]]

[[#Konfiguration der Floating-Lizenz | Konfiguration der Floating-Lizenz]]

== Installation von expecco auf Linux ==

expecco läuft auf allen aktuellen Linux-Distributionen (Ubuntu, RedHat, Fedora, Oracle Linux, Debian, (Open-)SuSE, ...).

=== Benötigte Linux Softwarepakete ===

expecco läuft sowohl auf 32- als auch auf 64-bit Linux Systemen. Sie können expecco wahlweise als 64-bit-Version oder 32-bit-Version installieren.
Falls sie ein 64-bit Linux einsetzten (das ist mittlerweile der Standard) empfehlen wir die 64-bit expecco-Version. '''Die 32-bit Linux-Version liefern wir nur noch auf Anfrage aus.'''

Es wird eine glibc in der Version >= 2.14 benötigt.

Installieren Sie über Ihren Paketmanager Ihrer Linux-Distribution folgende Pakete:

* <code>libXinerama</code>
* <code>libxrandr</code>
* <code>libXft</code>
* <code>libusb</code>
* <code>unixODBC</code>
* <code>odbcinst</code>
* <code>libglib-2_0-0</code>
* <code>gnuplot</code> (optional - falls Plot/Graph Aktionen benötigt)

Diese Pakete hängen von weiteren Paketen ab, die der Paketmanager automatisch mit installiert.

In '''Ubuntu (ab 15.04)''' installieren Sie die Pakete mit dem Kommando:

<code>sudo apt-get update && sudo apt-get install -y \
libxinerama1 libxft2 libxrandr2 unixodbc odbcinst libusb-1.0.0</code>

In '''OpenSUSE (Leap 15.x)''' installieren Sie die Pakete mit:

<code>sudo zypper install unixODBC libXinerama1 libXrandr2 libXft2 libusb-0_1-4 libusb-1_0-0</code>

==== Installation von 32-bit expecco auf 64-bit Linux (nicht empfohlen!) ====

Diese Konfiguration empfehlen wir nicht. Nutzen Sie stattdessen besser die 64-bit expecco Version.
Falls Sie expecco-32-bit doch auf 64-bit-Linux installieren wollen, benötigen Sie die Pakete in der 32-bit Ausführung.

Es wird eine glibc in der Version >= 2.10 benötigt.

In Ubuntu 64bit (ab 15.04 64-bit) für ein 32-bit expecco installieren Sie die Pakete mit dem Kommando:

<code>sudo apt-get update && sudo apt-get install -y \
libxinerama1:i386 libxft2:i386 libxrandr2:i386 unixodbc:i386 odbcinst:i386 libusb-1.0.0:i386</code>

=== Installation von expecco (Linux) ===

Sie erhalten eine E-Mail mit dem Link zu der expecco-Installationsdatei. Die Installationsdatei hat z.B. den Namen:

* expecco-23.2.0.69.package

wobei hier 23.2.0 der Versionsnummer von expecco entspricht und 69 der Build-Nummer. Die Installationsdatei enthält das expecco-Basispaket sowie die Plugins.

Für die Installation benötigen Sie bei einer erstmaligen Installation außerdem noch das ''autopackage'' Paket. Sie können es hier herunterladen: https://download.exept.de/transfer/autopackage/x86_64/autopackage.tar.bz2. Entpacken Sie das Archive und installieren Sie dieses durch das Ausführen der INSTALL Datei im Root Verzeichnis des Archives. Sie werden ggf. gefragt ob die GUI Komponenten vom "Autopackage" herunter geladen und installiert werden sollen. Wählen Sie "NEIN" aus, da diese nicht benötigt werden und unter Umständen zu Fehlern führen können.

Laden Sie die expecco-Installationsdatei und ggf. ''autopackage.tar.bz2'' in dasselbe Verzeichnis auf Ihrem Rechner.

Sie können die Installation als Benutzer ''root'' oder als normaler Benutzer ausführen. Wenn Sie expecco als Benutzer ''root'' installieren, wird expecco im Verzeichnis ''/opt/expecco/bin'' installiert. Bei einer Installation als normaler Benutzer, wird expecco in Ihrem Home-Verzeichnis nach ''.local/bin'' installiert.

Führen Sie aus:
bash ./expecco-23.2.0.69.package

expecco wird daraufhin installiert, es erscheint folgende Ausgabe:
# Preparing package: expecco - Graphical Test Modeling
# Checking for required C library versions ... passed
This may take a moment, please wait ... done
# Installing package: expecco - Graphical Test Modeling (package 1 of 1)
# 100%[==================================================] Extracting
# Copying files to /opt/expecco/plugin
# 100%[==================================================] Copying
# Copying files to /opt/expecco/packages/exept/technologyBridge
# Copying files to /opt/expecco/packages/exept/technologyBridge/javaBridge
# Copying files to /opt/expecco/packages/exept/technologyBridge/javaBridge/javaBridge_Server_Client
# 100%[==================================================] Copying
# Copying files to /opt/expecco/packages/stx/libsnmp
# Copying files to /opt/expecco/packages/stx/libsnmp/net-snmp-5.7.2/mibs
# 100%[==================================================] Copying
# Copying files to /opt/expecco/testsuites/libraries
# 100%[==================================================] Copying
# Copying files to /opt/expecco/bin
# 100%[==================================================] Copying
# Copying files to /opt/expecco/lib
# 100%[==================================================] Copying
# Copying files to /opt/expecco/packages/exept/expecco/doc
# 100%[==================================================] Copying
# Copying files to /opt/expecco/testsuites/libraries
# 100%[==================================================] Copying
# Copying files to /opt/expecco/testsuites/examples
# 100%[==================================================] Copying
# Copying files to /opt/expecco/packages/exept/expecco/reportGenerator/tools
# Copying files to /opt/expecco/packages/exept/pdf/afm
# 100%[==================================================] Copying
# Installing USB Dongle access...
# Updating package database...
The following package was successfully installed:
* expecco - Graphical Test Modeling
This installation used 478.74 MiB (502.00 MB) of disk space.
Remove this package by running package remove expecco from the command line.

=== Spezielle Installations-Optionen ===

Sie können das Verzeichnis, in das expecco installiert wird, wie folgt festlegen:

bash expecco-23.2.0.69.package
Installation als root nach /opt/expecco (Starten mit: /opt/expecco/bin/expecco)

bash expecco-23.2.0.69.package --prefix /opt/expecco-23.2
Installation als root nach /opt/expecco-23.2 (Starten mit: /opt/expecco-23.2/bin/expecco)

bash expecco-23.2.0.69.package --local-only
Installation als Benutzer nach $HOME/.local (Starten mit ~/.local/bin/expecco)

bash expecco-23.2.0.69.package --local-only --prefix ~/expecco
Installation als Benutzer nach $HOME/expecco (Starten mit ~/expecco/bin/expecco)

=== Update Installation von expecco (Linux) ===

Wie bei der Erstinstallation erhalten eine E-Mail mit dem Link zu der neuen expecco-Installationsdatei.
Bitte laden Sie das Installationsprogramme herunter. Bei der Ausführung des Installationsprogramms ''bash expecco-***.package'' erkennt expecco, dass eine andere Version bereits installiert wurde. Die alte expecco-Version wird mit allen Plugins automatisch deinstalliert. Ihre Einstellungen, Lizenzdateien und Ihre Testsuiten bleiben erhalten. Anschließend wird die neue expecco-Version wie bei der Erstinstallation (s.o.) installiert.

=== Deinstallieren ===

autopackage uninstall expecco

=== Lizenz installieren ===

Installieren Sie die Lizenz wie im nächsten Abschnitt beschrieben.

== Installation von expecco auf OS X ==

Achtung: die OS X-Version ist z.Z. im Beta Test und auf Anfrage verfügbar.

=== Benötigte macOS Softwarepakete ===

expecco läuft auf 64-bit x64_64 mac OS X Systemen (eine Version für ältere 32bit Maschinen ist nur noch auf Anfrage erhältlich; beachten Sie, dass die neueren OS X Versionen 32bit Programme nicht mehr unterstützen).
Es wird mindestens OS X 10.6 benötigt.

expecco benötigt XQuartz. Dieses sollten Sie vorher vom Apple Store oder [https://www.xquartz.org/ xquartz.org] installieren, falls nicht bereits vorinstalliert (kostenlos).

=== Installation von expecco (OS X) ===

Sie erhalten eine E-Mail mit dem Link zu der expecco-Installationsdatei. Die Installationsdatei hat z.B. den Namen:

* expecco-2.11.0.1.dmg

wobei hier 2.11.0 der Versionsnummer von expecco entspricht und 1 der Build-Nummer. Die Installationsdatei enthält das expecco-Basispaket sowie die Plugins.

Zur Installation öffnen Sie die "<code>dmg</code>"-Datei und verschieben "<code>expecco.app</code>" in den "<code>Application</code>"-Ordner (oder Ihren privaten "<code>Application</code>"-Ordner, oder jeden beliebigen anderen Ordner).

=== Deinstallation von expecco (OS X) ===
Sämtliche Dateien von expecco, mit Ausnahme Ihrer eigenen Suiten und Einstellungen sind im expecco.app Ordner. Löschen Sie diesen Ordner (und entleeren den Papierkorb) um expecco zu deinstallieren.
Ihre eigenen Einstellungen befinden sich im Homeverzeichnis unter ".expecco"; Ihre Suiten sind im Documentsordner, falls nicht explizit an anderer Stelle gespeichert.

== Konfiguration der Lizenz ==

Beim erstmaligen Ausführen erscheint ein Fenster, in dem eine Lizenz verlangt wird. Falls Sie bereits eine Lizenz installiert haben und diese wechseln möchten können Sie den selben Dialog unter "''Extras''" → "''Einstellungen''" → "''Lizenzinstallation''" öffnen, allerdings müssen Sie in diesem Fall nach dem Wechseln der Lizenz expecco neu starten.

Fall Sie expecco auf einem Computer ohne GUI installiert haben, kann das zuvor erwähnte Fenster nicht geöffnet werden. In dem Fall müssen Sie expecco auch auf einem Computer mit GUI installieren und dort den Dialog ausfüllen. Danach kopieren Sie die Settingsdatei "<code>~/.expecco/.expeccoPreferences</code>" oder "<code>C:\users\IhrBenutzer\AppData\Roaming\expecco\.expeccoPreferences</code>" und die Lizenzdatei "<code>~/.expecco/expeccoLicenseServerLicense</code>" oder "<code>C:\users\IhrBenutzer\AppData\Roaming\expecco\expeccoLicenseServerLicense</code>" auf den Computer ohne GUI.

[[#Konfiguration der Einzellizenz | Konfiguration der Einzellizenz]]

[[#Konfiguration der Floating-Lizenz | Konfiguration der Floating-Lizenz]]

[[#Auslösen einer Floating-Lizenz | Auslösen einer Floating-Lizenz]]

=== Konfiguration der Einzellizenz ===

Einzellizenzen werden üblicherweise mit einem USB-Dongle genutzt.
Ausnahmsweise können auch zeitlich limitierte Einzellizenzen ohne Dongle verwendet werden (sog. "''Demo Lizenz''").
In beiden Fällen erhalten Sie eine Lizenzdatei.
Lizenzdateien und Dongle müssen jeweils zusammenpassen, wobei eine Lizenzdatei auch zu mehreren Dongles desselben Kunden passen kann.

# falls Sie einen Dongle erhalten haben, stecken Sie ihn in einen freien USB-Port in Ihrem Rechner.
# Speichern Sie die Lizenzdatei auf Ihrem Rechner
# Ziehen Sie dann entweder die Datei mit der Maus aus dem Windows-Explorer in den Lizenzdialog, oder Sie wählen im Lizenzdialog Ihre Lizenzdatei direkt aus.
# Sie werden aufgefordert, expecco neu zu starten. Nach dem Neustart können Sie expecco nutzen.

Lizenzdateien ohne Dongle sind zeitlich beschränkt.
Wenn Sie versehentlich den expecco-Dongle nicht in Ihren Rechner eingesteckt haben und expecco starten, erhalten Sie einen Hinweis, dass die Lizenz abgelaufen sei.
Sobald Sie den Dongle einstecken (bevor Sie expecco starten), erscheint dieser Hinweis beim Start von expecco nicht mehr.

Solange Sie mit expecco arbeiten, wird überwacht, ob der Dongle vorhanden ist.
Wenn Sie den Dongle währenddessen aus Ihrem Rechner entfernen, erhalten Sie einen Hinweis und können keine Tests mehr ausführen oder verändern.
Sie können allerdings die gerade bearbeitete Testsuite noch abspeichern, so dass keine Änderungen verloren gehen.

=== Konfiguration der Floating-Lizenz ===

Um eine Floating-Lizenz zu nutzen, benötigen Sie einen expecco-Lizenzserver. Diesen (bzw. den Downloadlink) erhalten Sie von uns mit den Floatinglizenzen. Der Lizenzserver ist eine HTTP-Serviceanwendung, die auf einem beliebigen Rechner in einer Cloud oder Ihrer Firma oder Abteilung installiert wird. Sie läuft ohne eigenes Fenster, und wird über einen beliebigen WebBrowser bedient.

Der Lizenzserver ist unter einem Rechnername bzw. IP-Adresse und einer Portnummer zu erreichen.
Der Administrator des Lizenzservers kann Ihnen diese Informationen geben, falls er eine andere als die default-Portnummer konfiguriert hat.
Es muss sichergestellt sein, dass eine TCP-Verbindung zum entsprechenden Port im Lizenzserver aufgebaut werden kann.
Router und Firewalls sind gegebenenfalls entsprechend zu konfigurieren bzw. Ports freizuschalten.

Beim Start von expecco öffnet sich der Lizenzdialog.
Wählen Sie hier die Lizenzserver-Kachel aus.
Tragen Sie den Rechnernamen bzw. die IP-Adresse sowie die Portnummer des Lizenzservers ein.
Im allgemeinen kann die vorgeschlagene default Portnummer unverändert übernommen werden.
Lediglich in Netzwerken, bei denen nur bestimmte Ports durch Firewalls oder Router durchgeschaltet werden ist es u.U. notwendig, eine andere Portnummer zu verwenden.
Der Administrator des Lizenzservers kann Ihnen in diesem Fall diese Informationen geben

Sie können jetzt auswählen, welche expecco-Ausprägung Sie verwenden wollen: ''expecco-developer'' oder ''expecco-runtime''.
Über die Schaltfläche "''Plugin-Liste vom Server aktualisieren''" erhalten Sie die verfügbaren Plugins (bzw. Plugins für die noch Floating-Lizenzen verfügbar sind).
Wählen Sie die Plugins aus, die Sie für Ihre Tests benötigen.
Von den meisten Plugins benötigen Sie nur eine Lizenz.
Einzelne Plugins können für auf mehrere Rechner verteilte Tests mehr als eine Lizenz von einem Plugin benötigen - Sie können das für derartige Plugins angeben.
Im Dialog wird angezeigt, wie viele Lizenzen für ein bestimmtes Plugin auf dem Lizenzserver momentan noch zur Verfügung stehen.
Per Tooltip können Sie auch in Erfahrung bringen, wie viele Lizenzen generell vorhanden sind.
Die Differenz sind die momentan von anderen Benutzern verwendeten Lizenzen.

Über die Schaltfläche "''Lizenzdatei installieren''" werden die Lizenzen vom Lizenzserver abonniert.
Starten Sie jetzt expecco neu, damit die lizenzierten Plugins geladen werden.

Wenn expecco beendet wird, werden alle Lizenzen wieder an den Lizenzserver zurück gegeben.
Expecco erneuert regelmäßig die Lizenzen vom Lizenzserver.
Wenn der Lizenzserver über einen gewissen Zeitraum nicht mehr erreichbar sein sollte (ca. 15 Minuten), wird expecco gesperrt, so dass keine Tests mehr ausgeführt oder verändert werden können. Geänderte Testsuiten können aber noch abgespeichert werden.

Wenn expecco nicht regulär beendet wurde, z.B. wenn der Rechner einfach ausgeschaltet wird, fallen die Lizenzen nach diesem Zeitraum an den Lizenzserver zurück und können dann von anderen Benutzern genutzt werden.

expecco merkt sich, welche Lizenzen zuletzt abonniert wurden.
Wenn expecco gestartet wird, versucht es, die zuletzt abonnierten Lizenzen wieder zu erhalten.
Sollte das nicht möglich sein, da alle Lizenzen momentan vergeben sind, erscheint der Lizenzdialog, in dem die nicht oder nur teilweise erhaltenen Lizenzen rot unterlegt sind.

Wenn Sie neue Lizenzen benötigen oder bisher verwendete Lizenzen nicht mehr benötigen, können Sie die anzufordernden Lizenzen jederzeit über den Lizenzdialog anpassen.
Sie erreichen ihn über das Menü "''Extras''" → "''Einstellungen''" → "''Lizenzinstallation''".

=== Auslösen einer Floating-Lizenz ===

Floatinglizenzen können auch ohne bestehende Verbindung zum Lizenzserver ausgelöst werden (sog. "''road warrior'' Lizenzen"). Dies ermöglicht es Ihnen, auch zuhause, bei Kunden oder in isolierten Labors mit expecco zu arbeiten, ohne dass dafür ein Dongle benötigt wird.

Auch wenn Ihr expecco keine Netzwerkverbindung hat, ist es möglich expecco mit einer Floating-Lizenz zu betreiben. Die Lizenz für expecco wird für eine bestimmte Zeitspanne ausgelöst. Nachdem diese Zeitspanne verstrichen ist, wird die ausgelöste Lizenz automatisch wieder zurückgegeben (eingegliedert). Bitte beachten Sie, dass es '''keine Möglichkeit gibt, eine ausgelöste Lizenz vor ihrem Ablauf wieder zurückzugeben!'''

Hierfür brauchen Sie einen Lizenzservice (expecco ALM), aus welchem die Floating-Lizenz ausgelöst wird. Der Lizenzserver benötigt einen speziellen Dongle, der die Funktion unterstützt. '''Falls der Lizenzserver ohne Dongle an eine MAC-Adresse gebunden ist, steht diese Funktion nicht zur Verfügung!'''

Zum Auslösen einer Floating-Lizenz starten Sie expecco und rufen Sie den Lizenzdialog unter "''Extras''" → "''Einstellungen''" → "''Lizenzinstallation''" auf (beim erstmaligem Start erscheint dieser automatisch) und navigieren Sie in den Reiter "Ausgelöste Floating-Lizenz".

Dort haben Sie folgende Möglichkeiten:
==== Eine Anfrage zum Auslösen einer Floating-Lizenz erstellen ====
Stellen Sie sich Ihre gewünschte Lizenz zusammen. Definieren Sie den Typ (Runtime / Pro), die Plugins und wie lange Sie die Lizenz auslösen möchten. Sie können Ihre Anfrage dann entweder in eine Datei speichern oder in die Zwischenablage legen.

Rufen Sie nun das Web-Interface des Lizenzservices (expecco ALM) in einem Webbrowser auf. Navigieren Sie in expecco ALM zu "''Lizenzservice''" → "''expecco Lizenzen''" → "''Lizenz auslösen''". Dort können Sie dann Ihre Anfrage entweder über Datei hochladen oder aus der Zwischenablage in das freie Feld einfügen.

Nach dem erfolgreichen Einspielen Ihrer Anfrage wird Ihnen Ihre Anfrage zur Gegenprüfung im Detail angezeigt. Sie können hier die Dauer der Auslösung ggf. erneut anpassen. Über den Knopf "Auslösen bestätigen" wird die Lizenz endgültig ausgelöst. Danach ist diese Lizenz bis zum Ablauf der Dauer ausschließlich für das expecco, von welchem die Anfrage erstellt wurde reserviert. Ihnen wird anschließend der Bestätigungsschlüssel angezeigt. Diesen können Sie wiederum als Datei speichern oder über Rechtsklick "Kopieren" in die Zwischenablage legen.

Jetzt müssen Sie diesen Bestätigungsschlüssel an expecco übertragen (über USB-Stick, Zuruf, Telefon usw.) und eingeben oder die Datei auswählen.

==== Eine bereits ausgelöste Floating-Lizenz in Betrieb nehmen ====
Falls Sie expecco aus Versehen während dem Prozess des Auslösens geschlossen haben oder der Prozess durch etwas ähnlich unterbrochen wurde, ist die ausgelöste Lizenz nicht verloren. Sie können diese Lizenz anhand Ihrer Anfrage und zugehörigem Bestätigungsschlüssel jederzeit in expecco aktivieren.

Öffnen Sie dazu den Lizenzservice (expecco ALM) und navigieren Sie nach "''Lizenzservice''" → "''expecco Lizenzen''" → "''Im Einsatz''". Suchen Sie in dieser Liste nach einer passenden Lizenz. Eine passende Lizenz erkennen Sie bspw. an der Spalte "Rechnername", diese Spalte sollte mit dem Rechnernamen auf dem expecco installiert ist übereinstimmen. Übertragen Sie die Anfrage sowie den Bestätigungsschlüssel aus den Spalten "Auslöse-Anfrage-Datei" und "Auslösungsschlüssel" zu expecco.

In expecco müssen Sie die Auslöse-Anfrage-Datei auswählen und diese dann mit dem Bestätigungsschlüssel aktivieren.

==== Die aktuell verwendete ausgelöste Floating-Lizenz verlängern ====

Das Verlängern einer ausgelösten Floating-Lizenz ist nur möglich, solange diese noch gültig ist. Nach dem Ablauf einer ausgelösten Lizenz wird diese im Lizenzserver gelöscht und Sie müssen diese durch eine neue Anfrage erneuern (i.e. eine neue Lizenz auslösen).

Öffnen Sie dazu den Lizenzservice (expecco ALM) und navigieren Sie nach "''Lizenzservice''" → "''expecco Lizenzen''" → "''Im Einsatz''". Suchen Sie in dieser Liste nach einer passenden Lizenz. Eine passende Lizenz erkennen Sie bspw. an der Spalte "Rechnername". Diese Spalte sollte mit dem Rechnernamen, auf dem expecco installiert ist, übereinstimmen.

Klicken Sie nun auf "Verlängern". Sie werden automatisch auf die Seite "Lizenz verlängern" weitergeleitet. Ihre Lizenz ist bereits vorselektiert. Sie können nun das gewünschte Datum eingeben. Danach wird Ihnen ein neuer Bestätigungsschlüssel angezeigt, diesen müssen Sie in expecco eingeben.

=== Änderung des Lizenztyps nach der Installation ===

Über das Menü "''Extras''" → "''Einstellungen''" → "''Lizenzinstallation''" können Sie die Lizenz nachträglich ändern.

'''Die Änderung des Lizenztyps werden permanent gespeichert, wenn Sie die Einstellung mit der Schaltfläche "Sichern" abspeichern.'''

== Weitere Hilfspakete und Frameworks ==

Die Basisinstallation wie oben beschrieben beinhaltet bereits die meisten normalerweise benötigten Komponenten. Abhängig von später durchzuführenden Tests und benötigter Software können (sollten) weitere Pakete ebenfalls installiert werden. Hinweise dazu finden Sie im Dokument: [[Installing_additional_Frameworks/en | "Installing additional Frameworks"]].

Wir empfehlen folgende Pakete:
* [[Installing_additional_Frameworks/en#Java_Installation_.28for_Groovy_Actions.2C_Web-_and_Mobile_Testing.29|Java Runtime or JDK]]
* [[Installing_additional_Frameworks/en#Python_Installation_.28for_Python_Actions.29|Python]]
* [[Installing_additional_Frameworks/en#OCR_.28Optical_Character_Recognition.29|Tesseract]] falls Sie OCR (Optical Character Recognition) zum Extrahieren von Texten aus Bildern und Bildschirmabzügen benötigen.

Ausserdem sinnvoll (aber seltener benötigt):
* [[Installing_additional_Frameworks/en#Node_Installation_.28for_Node.js_Actions.29|Node]]

Falls Sie Aktionen in C or C++ schreiben wollen (müssen):
* [[Installing_additional_Frameworks/en#C_Compiler_Toolchain_Installation_.28for_C-Actions.29|C Compiler Toolchain]]

== Patches und Aktualisierungen ==

Exept stellt auch zwischen zwei Major Releases zu Verfügung in unregelmäßigen Abständen oder auf Anfrage Patches und Erweiterungen.

Patches sind versionsabhängig; d.h. ein Patch für expecco Version 23.1 ist nicht für andere Versionen zu verwenden.
Normalerweise beinhaltet jede neue Major Release (z.B. 24.1) alle Patches aller Vorgängerversionen.
Oft sogar mehr Funktionalität. Alte Patches sollten daher nicht in neuere Versionen eingespielt werden,
und expecco lehnt auch solche Patches ab. Es besteht also keine Gefahr, dass diese aus Versehen eingespielt werden.

Die Patches kommen in Dateien paarweise: eine ".expeccoPatch" und eine ".info" Datei.
Letztere beinhaltet eine textuelle Beschreibung; erstere den eigentlichen Patch.
Die Patches sind signiert, und expecco wird nur patch Dateien welche von exept signiert sind akzeptieren.

Die patch Dateien können auf mehrere Arten sowohl manuell als auch automatisch heruntergeladen und eingespielt werden.
Sie befinden sich physikalisch auf dem download host von exept, unter "http://dowloads.exept.de" und "ftp://ftp.exept.de/downloads".

=== Automatisch vom Exept Download Server ===

Wenn sie Zugriff aufs Internet mit http (port80) oder https (port 443) haben,
gehen sie zu "Extras" - "Einstellungen" - "Software Aktualisierung".
Und verifizieren die Einstellungen zu "Patch Server".
Zum Test der Verbindung klicken sie auf "Jetzt nach Updates suchen".

Sie können oben auswählen, wann und wie oft expecco nach Updates schauen soll.

=== Automatisch von einem hauseigenen Download Server ===

Falls ihr Testrechner keinen Zugriff aufs Internet hat, aber ein anderer Rechner im Hausnetz erreichbar ist, können sie die Patches auch wie unten beschrieben auf diese Maschine herunterladen und von ihren Testrechnern die Patches dort abholen.
Dies hat den Vorteil, dass der download nur einmal durchgeführt werden muss, und sie selbst Kontrolle über die Patches haben.

Gehen sie dazu wie oben beschrieben zum Einstellungsdialog, und geben den Namen und Pfad ihres Servers ein. Dort sollte dann ein Dateiservice mit unten beschriebener Dateistruktur zu finden sein (z.B. ein entsprechen aufgesetzter apache Server).

=== Automatisch von einem hauseigenen Lizenz Server ===

Wenn Sie keinen apache Server aufsetzen wollen oder können, aber einen Lizenzserver verwenden, können sie die patches auch auf dessen Rechner unter einem beliebigen Verzeichnis ablegen und den Lizenzserver entsprechend konfigurieren.

Im Lizenzserver (AIDYMO) gehen sie zu den "Einstellungen" - "System", und finden unten in der Maske unter "Sonstige" eine Checkbox "Patches Service". Schalten sie diese Box ein, und geben darunter den Pfad zu dem patches Verzeichnis (auf dem Rechner des Lizenzservers).
Die Orderstruktur darunter entspricht der unten beschriebenen unter "expecco". I.e. "<versionsNr>/patches/..."

=== Manuell ===

Falls ihr Testrechner isoliert vom Internet oder dem Hausnetz arbeitet (z.B. in einem Cleanroom oder Prüfstand),
müssen die Patches zunächst auf den Rechner gebracht werden. Dies kann z.B. über ein Medium (USB-Stick) oder ein Netzlaufwerk erfolgen.

Unter dem jeweiligen Hauptverzeichnis (siehe oben) befindet sich ein Ordner per Release, und darunter die patch- und info Dateien.
Also z.B.:
https://download/expecco/23.2.0/patches
0001_fix1.expeccoPatch
0001_fix1.info
0002_feature1.expeccoPatch
0002_feature1.info
https://download/expecco/24.1.0/patches
0001_fix2.expeccoPatch
0001_fix2.info
usw.

Falls der automatische update versagt, können Sie die Dateien als fallback im Browser herunterladen (sichern als),
in einem Ordner sammeln und wie unten beschrieben manuell einspielen.

Falls es sich um einen Individualpatch für Sie persönlich handelt, kann er ihnen auch per email zugesandt, oder in AIDYMO als Anhang übergeben werden.

Bringen sie dazu die ".expeccoPatch" Dateien auf den Testhost (z.B. in ein Temp Verzeichnis), und
wählen im "Extras" -> "Maintenance" -> "Install Patch from File".
Im geöffneten Dialog wählen Sie die entsprechen(n) Datei(en) an und bestätigen sie.

Diesen Vorgang müssen Sie nur einmal durchführen; mit jedem Neustart werden die Patches automatisch neu installiert.
Die temporären Dateien können sie nach der Installation löschen; sie werden nicht mehr gebraucht.

Release Notes 25.x

2025-07-22T08:12:10Z

Sv: /* Release 25.1 */

See also: [[Release Notes 24.x]]
 

== Release 25.1 ==
*Improvement: additional "Info" tab in inspector views
*Improvement: less memory usage in the activity log
*Improvement: better error messages and more links to settings from the activity log's error message
*Improvement: additional units and conversions in the [[PhysicalValues/en|physical values framework]]
*Improvement: more precision in the [[Numeric_Limits/en#Higher_Precision_Numbers|high precision trigonometric and math functions]]
*Improvement: WindowsAutomation: Plugn Update to FlaUI 5
*Improvement: Mobile Testing: Better Device Lock/Unlock Support
*Improvement: StandardLibrary: "File [ *CSV ]" blocks got an additional "characterEncodeing" pin (useful for reading/writing e.g. utf-8 encoded CSV files)
*Improvement: ExcelLib: better documentation. Now requires the openpyxl package version >= 3.1.5.
*Improvement: better model language editor (translate and fetch-strings functions)
*Improvement: ODBClibrary: improved compatibility with different database vendors (supports the CedarDB database)
*Feature: translate and spell check in the workspace window
*Feature: EditLock of suites loaded from expeccoALM / AIDYMO
*Feature: Start Test in expeccoALM / AIDYMO (via expecco)
*Feature: new library containing expeccoALM control actions (those from the AIDYMO menu)
*Fix: the version diff viewer (did not correctly copy changed attachment files)

Lizenzserver expecco ALM

2025-07-09T08:41:35Z

Sv: /* Installation */

==Übersicht==

Der expecco Lizenzserver dient der zentralen Verwaltung von expecco Lizenzen. Durch den Lizenzserver kann expecco auf verschiedenen Rechnern (sowohl Entwicklungs- als auch reine Testausführungsrechner) ohne Dongle und lokale Lizenzdatei auf allen erreichbaren Rechnern im Netz installiert und ausgeführt werden.

Lizenzen werden dabei von den expecco-Rechnern vom Lizenzserver angefordert, im Lizenzserver reserviert,
und nach der Sitzung bzw. Testlauf wieder zurückgegeben. Damit können mehr Nutzer (allerdings nicht gleichzeitig) mit expecco arbeiten als Lizenzen erworben wurden.

Lizenzen sind kryptographisch gesicherte Dateien, welche nur in Verbindung mit einem von eXept gelieferten Lizenzserver-Dongle gelesen bzw. genutzt werden können. Lizenzen sind Dongle-spezifisch. Es ist also nicht notwendig, Maßnahmen zum Schutz vor Diebstahl oder Kopieren von Lizenzdateien zu ergreifen. Allerdings ist ein Verlust des Dongles aus nahe liegenden Gründen zu vermeiden.

{{SEITENTITEL:Lizenzservice Installation}}

== Voraussetzungen ==
Wir empfehlen expecco ALM auf einem durchgehend verfügbaren Server mit Windows Server 2012 / Windows 10 oder höher zu installieren. Die Installation auf anderen Betriebssystemen (wie z.B. Linux) wäre bei Bedarf auch möglich. Ebenso ist die Installation in einer Cloud möglich, dort ist der Betrieb ohne Dongle möglich.

Damit expecco ALM flüssig arbeiten kann, werden folgende Hardware-Anforderungen an den Server gestellt:
 - ein "dezidierter" Prozessor mit mindestens 2 GHz
 - mindestens 1 GB Arbeitsspeicher (ausschließlich für expecco ALM)
 - mindestens 10 GB Festplattenspeicher (je nach Größe der Daten die expecco ALM verwalten soll)

Stellen Sie sicher, dass dieser Server für alle Clients erreichbar ist. Clients sind alle Rechner der expecco ALM Benutzer, Rechner die expecco ALM zur Testausführung dienen und Rechner mit "Floating" lizenziertem expecco. Bei Problemen bezüglich der Erreichbarkeit wenden Sie sich bitte an Ihren Netzwerkadministrator.

== Installation ==

Bitte halten Sie Ihre Lizenzdatei und Ihren Dongle für die Installation von expecco ALM bereit. 
Für die Installation in der Cloud liefern wir eine Lizenzdatei mit entsprechender Mac-Adresse.

Ihre Lizenzdatei und eine Verknüpfung zum aktuellen expecco ALM Setup haben wir Ihnen per E-Mail zu kommen lassen. Der Installer hat folgenden Namen "expecco ALM 1.9.0.1 Setup.exe", wobei die Versionsnummer abweichen kann. Ihren Dongle haben wir per Post an Sie versendet (es sei denn Sie evaluieren expecco ALM oder nutzen die Cloud Variante mit der Mac-Adressen-Bindung).

Gehen Sie bitte wie folgt vor:
* Laden Sie den expecco ALM Installer auf dem Server, auf dem expecco ALM künftig laufen soll, herunter
* Legen Sie Ihre Lizenzdatei ebenfalls auf dem Server ab
* Verbinden Sie Ihren Dongle mit dem Server (Wenn Sie expecco ALM evaluieren oder die Cloud Variante mit der Mac-Adressen-Bindung nutzen, überspringen Sie diesen Schritt)
* Führen Sie den expecco ALM Installer ("expecco ALM ?.?.?.? Setup.exe" bzw. unter Linux "expecco ALM ?.?.?.? Setup.package") aus

Für Linux werden zusätzliche Pakete der Linux-Distribution benötigt. Diese sind [[Installation#Installation_von_expecco_auf_Linux|hier]] aufgeführt.

Nachdem der Installer erfolgreich ausgeführt wurde, läuft expecco ALM bereits als Service. Auf Ihrem Desktop wurde eine Verknüpfung zu expecco ALM angelegt. Es wurde auch ein Ordner für expecco ALM in Ihrem Startmenü erstellt. Dort können Sie unter "Konfiguration" den Port ändern (Standard ist Port 8081) oder über die "Logdatei" eventuelle Probleme feststellen.

[[Datei:InstallAlmLicense.png|mini|Anhang 1]]
Über die Verknüpfung auf Ihrem Desktop lässt sich expecco ALM mit Ihrem Standardbrowser öffnen. Es wird eine Seite zum Installieren Ihrer expecco ALM Lizenz angezeigt (Anhang 1). Über "Lizenzdatei installieren" können Sie Ihre Lizenzdatei (die Sie bereits auf dem Server abgelegt haben) auswählen. Nach dem expecco ALM Ihre Lizenzdatei akzeptiert hat, können Sie diese entfernen. Wenn bereits eine gültige Lizenz installiert ist, wird stattdessen die Anmeldeseite angezeigt. Falls es sich bei Ihnen um eine Erstinstallation handelt, können Sie sich mit Anmeldenamen "admin" und Kennwort "admin" anmelden.

Falls eine leere Seite oder eine Fehlerseite angezeigt wird, probieren Sie einen anderen Port aus und/oder schauen Sie in der Logdatei nach Fehlermeldungen.

== SSL-Verschlüsselung / Proxy-Server ==
expecco ALM unterstützt aktuell noch nicht direkt SSL-Verschlüsselung. Über einen Proxy-Server ist diese aber problemlos einzurichten, z.B. über einen Apache-Server. Falls auf ihrem Server weitere Webseiten gehostet werden, ist dies ja ohnehin erforderlich, da sich nicht mehrere Prozesse gleichzeitig an den Port 443 binden können.

Eine Apache2 VirtualHost-Konfiguration würde entsprechend so aussehen (angenommen expecco ALM läuft mit Port 8465 - erforderliche Anpassung für ihre Konfiguration fett):
<VirtualHost *:443>
ServerName expeccoalm.xyz.de
ServerAdmin webmaster@xyz.de

Include /etc/letsencrypt/ssl-xyz.de.conf

SSLProxyEngine On

RewriteEngine on
RewriteCond %{HTTP:Upgrade} =websocket [NC]
RewriteRule /(.*) ws://localhost:8465/$1 [P,L]
RewriteCond %{HTTP:Upgrade} !=websocket [NC]

ProxyPass / http://localhost:8465/ nocanon
ProxyPassReverse / http://localhost:8465/
</VirtualHost>

Die SSL-Parameter mit dem Pfaden zu Ihren Zertifkaten uns Schlüsseln würden in diesem Konfigurations-Beispiel in der Apache-globalen Datei /etc/letsencrypt/ssl-xyz.de.conf liegen.

== Hinweise zur Lizenzierung ==
Wenn Sie expecco ALM erworben haben, erhalten Sie einen Dongle und eine Lizenzdatei. Falls Sie expecco ALM evaluieren, erhalten Sie ausschließlich die Lizenzdatei. Die Lizenzdatei beinhaltet eine für Sie individuelle expecco ALM Lizenz. So sind zum Beispiel: Der Name Ihrer Firma, für Sie freigeschaltete Module oder die Gültigkeitsdauer in der Lizenz hinterlegt. Der Dongle muss (insofern Sie expecco ALM erworben haben) ständig mit dem Server, auf dem expecco ALM ausgeführt wird, verbunden sein. Falls Sie den Dongle während des Betriebs abziehen, wird expecco ALM seinen Dienst einstellen.

== Lizenz wechseln ==
[[Datei:ChangeAlmLicense.png|mini|Anhang 2]]
Falls Sie eine aktuelle expecco ALM Version haben, können Sie eine neue Lizenzdatei "expecco ALM Lizenz *.lic" über das Webinterface von expecco ALM einspielen. Betrachten Sie dazu den angehängten Screenshot (Anhang 2).

Fall Sie eine ältere expecco ALM Version haben, müssen Sie folgendermaßen vorgehen:
 - Da Sie expecco ALM später neustarten müssen, tätigen Sie entsprechende Vorsorgemaßnahmen (Bspw. Benutzer abmelden, Datenbank sichern usw.)
 - Melden Sie sich auf dem Computer, der expecco ALM betreibt an
 - Begeben Sie sich in folgendes Verzeichnis "C:\Windows\SysWOW64\config\systemprofile\AppData\Roaming\expecco_ALM" oder falls es sich um ein 32Bit Betriebssystem handelt "C:\Windows\system32\config\systemprofile\AppData\Roaming\expecco_ALM" und löschen Sie die Datei "expecco_ALM.lic"
 - Starten Sie den expecco ALM Service über den Windows-Service-Manager neu oder beenden Sie über den Windows-Task-Manager den Prozess "expecco_ALM.exe", in letzterem Fall wird der Windows-Service-Manager expecco ALM automatisch neustarten.
 - Nun können Sie das expecco ALM Webinterface aufrufen. Es wird eine Seite zum Installieren Ihrer expecco ALM Lizenz angezeigt (Anhang 1). Über "Lizenzdatei installieren" können Sie Ihre Lizenzdatei. auswählen. Nach dem expecco ALM Ihre Lizenzdatei akzeptiert hat, können Sie diese entfernen.

== Einbringen von expecco Floating-Lizenzen ==
Der Lizenzservice von expecco ALM vergibt verfügbare expecco Floating-Lizenzen aus einem bestimmten Pool. 
In diesen zunächst leeren Pool können von eXept erworbene expecco Floating-Lizenzen eingebracht werden.
 
Diese expecco Floating-Lizenzen erhalten Sie als Lizenzdatei(en) üblicherweise per E-Mail. 
Eine Lizenzdatei kann eine oder mehrere expecco Floating-Lizenzen auch für verschiedene Komponenten (Basissystem, Plugins und Erweiterungen) enthalten. 
Sie können auch jederzeit weitere expecco Floating-Lizenzen erwerben und in den Pool einbringen.
 
expecco Floating-Lizenzen werden immer spezifisch für eine expecco ALM Lizenz erstellt und sind nur mit dieser und deren Dongle nutzbar. 
Es ist also nicht notwendig solche Lizenzdateien unter Verschluss zu halten oder über eine sichere Verbindung auszutauschen. 
Allerdings sollten Sie den Dongle sicher aufbewahren bzw. Diebstahl vorbeugen.
 
Zur Einbringen einer expecco Floating-Lizenz öffnen Sie expecco ALM und melden Sie sich an. 
Jetzt navigieren Sie über die obere Hauptnavigationsleiste zum "Lizenzservice" Modul.
 
Sie befinden sich nun im Lizenzservice und Ihnen wird die Liste der installierten expecco Floating-Lizenzen angezeigt. 
Wechseln Sie zur Registerkarte "expecco Lizenzdateien". 
Navigieren Sie mithilfe des Navigationsmenüs auf der linken Seite zu "Hochladen/Upload". 
Hier können Sie nun durch ein einfaches Hochladen Ihrer expecco Floating-Lizenzen selbige in den Pool einbringen. 
In der zuvor genannte Liste werden nun die eben hochgeladenen expecco Floating-Lizenzen anzeigt. 
Diese sind von nun an auch von entfernten expecco Clients abrufbar. 
Sie können auch jederzeit weitere expecco Floating-Lizenzen erwerben und in den Pool einbringen.

== Lizenz Übersicht ==
Welche einzelnen expecco Floating-Lizenzen verfügbar oder vergeben sind, 
erfahren Sie indem Sie zur Registerkarte "expecco Lizenzen" wechseln. 
Insbesondere ist hieraus ersichtlich, welcher Rechner/Benutzer welche expecco Floating-Lizenz aktuell nutzt. 
Dies ist beispielsweise sinnvoll, wenn ein expecco Client seine Sitzung versehentlich nicht beendet hat, 
und andere Nutzer eine entsprechende Lizenz benötigen.

Lizenzserver expecco ALM

2025-07-09T08:41:02Z

Sv: /* Installation */

==Übersicht==

Der expecco Lizenzserver dient der zentralen Verwaltung von expecco Lizenzen. Durch den Lizenzserver kann expecco auf verschiedenen Rechnern (sowohl Entwicklungs- als auch reine Testausführungsrechner) ohne Dongle und lokale Lizenzdatei auf allen erreichbaren Rechnern im Netz installiert und ausgeführt werden.

Lizenzen werden dabei von den expecco-Rechnern vom Lizenzserver angefordert, im Lizenzserver reserviert,
und nach der Sitzung bzw. Testlauf wieder zurückgegeben. Damit können mehr Nutzer (allerdings nicht gleichzeitig) mit expecco arbeiten als Lizenzen erworben wurden.

Lizenzen sind kryptographisch gesicherte Dateien, welche nur in Verbindung mit einem von eXept gelieferten Lizenzserver-Dongle gelesen bzw. genutzt werden können. Lizenzen sind Dongle-spezifisch. Es ist also nicht notwendig, Maßnahmen zum Schutz vor Diebstahl oder Kopieren von Lizenzdateien zu ergreifen. Allerdings ist ein Verlust des Dongles aus nahe liegenden Gründen zu vermeiden.

{{SEITENTITEL:Lizenzservice Installation}}

== Voraussetzungen ==
Wir empfehlen expecco ALM auf einem durchgehend verfügbaren Server mit Windows Server 2012 / Windows 10 oder höher zu installieren. Die Installation auf anderen Betriebssystemen (wie z.B. Linux) wäre bei Bedarf auch möglich. Ebenso ist die Installation in einer Cloud möglich, dort ist der Betrieb ohne Dongle möglich.

Damit expecco ALM flüssig arbeiten kann, werden folgende Hardware-Anforderungen an den Server gestellt:
 - ein "dezidierter" Prozessor mit mindestens 2 GHz
 - mindestens 1 GB Arbeitsspeicher (ausschließlich für expecco ALM)
 - mindestens 10 GB Festplattenspeicher (je nach Größe der Daten die expecco ALM verwalten soll)

Stellen Sie sicher, dass dieser Server für alle Clients erreichbar ist. Clients sind alle Rechner der expecco ALM Benutzer, Rechner die expecco ALM zur Testausführung dienen und Rechner mit "Floating" lizenziertem expecco. Bei Problemen bezüglich der Erreichbarkeit wenden Sie sich bitte an Ihren Netzwerkadministrator.

== Installation ==

Bitte halten Sie Ihre Lizenzdatei und Ihren Dongle für die Installation von expecco ALM bereit. 
Für die Installation in der Cloud liefern wir eine Lizenzdatei mit entsprechender Mac-Adresse.

Ihre Lizenzdatei und eine Verknüpfung zum aktuellen expecco ALM Setup haben wir Ihnen per E-Mail zu kommen lassen. Der Installer hat folgenden Namen "expecco ALM 1.9.0.1 Setup.exe", wobei die Versionsnummer abweichen kann. Ihren Dongle haben wir per Post an Sie versendet (es sei denn Sie evaluieren expecco ALM oder nutzen die Cloud Variante mit der Mac-Adressen-Bindung).

Gehen Sie bitte wie folgt vor:
* Laden Sie den expecco ALM Installer auf dem Server, auf dem expecco ALM künftig laufen soll, herunter
* Legen Sie Ihre Lizenzdatei ebenfalls auf dem Server ab
* Verbinden Sie Ihren Dongle mit dem Server (Wenn Sie expecco ALM evaluieren oder die Cloud Variante mit der Mac-Adressen-Bindung nutzen, überspringen Sie diesen Schritt)
* Führen Sie den expecco ALM Installer ("expecco ALM ?.?.?.? Setup.exe" bzw. unter Linux "expecco ALM ?.?.?.? Setup.package") aus

Für Linux werden zusätzliche Pakete der Linux-Distribution benötigt. Diese werden [[Installation#Installation_von_expecco_auf_Linux|hier]] aufgeführt.

Nachdem der Installer erfolgreich ausgeführt wurde, läuft expecco ALM bereits als Service. Auf Ihrem Desktop wurde eine Verknüpfung zu expecco ALM angelegt. Es wurde auch ein Ordner für expecco ALM in Ihrem Startmenü erstellt. Dort können Sie unter "Konfiguration" den Port ändern (Standard ist Port 8081) oder über die "Logdatei" eventuelle Probleme feststellen.

[[Datei:InstallAlmLicense.png|mini|Anhang 1]]
Über die Verknüpfung auf Ihrem Desktop lässt sich expecco ALM mit Ihrem Standardbrowser öffnen. Es wird eine Seite zum Installieren Ihrer expecco ALM Lizenz angezeigt (Anhang 1). Über "Lizenzdatei installieren" können Sie Ihre Lizenzdatei (die Sie bereits auf dem Server abgelegt haben) auswählen. Nach dem expecco ALM Ihre Lizenzdatei akzeptiert hat, können Sie diese entfernen. Wenn bereits eine gültige Lizenz installiert ist, wird stattdessen die Anmeldeseite angezeigt. Falls es sich bei Ihnen um eine Erstinstallation handelt, können Sie sich mit Anmeldenamen "admin" und Kennwort "admin" anmelden.

Falls eine leere Seite oder eine Fehlerseite angezeigt wird, probieren Sie einen anderen Port aus und/oder schauen Sie in der Logdatei nach Fehlermeldungen.

== SSL-Verschlüsselung / Proxy-Server ==
expecco ALM unterstützt aktuell noch nicht direkt SSL-Verschlüsselung. Über einen Proxy-Server ist diese aber problemlos einzurichten, z.B. über einen Apache-Server. Falls auf ihrem Server weitere Webseiten gehostet werden, ist dies ja ohnehin erforderlich, da sich nicht mehrere Prozesse gleichzeitig an den Port 443 binden können.

Eine Apache2 VirtualHost-Konfiguration würde entsprechend so aussehen (angenommen expecco ALM läuft mit Port 8465 - erforderliche Anpassung für ihre Konfiguration fett):
<VirtualHost *:443>
ServerName expeccoalm.xyz.de
ServerAdmin webmaster@xyz.de

Include /etc/letsencrypt/ssl-xyz.de.conf

SSLProxyEngine On

RewriteEngine on
RewriteCond %{HTTP:Upgrade} =websocket [NC]
RewriteRule /(.*) ws://localhost:8465/$1 [P,L]
RewriteCond %{HTTP:Upgrade} !=websocket [NC]

ProxyPass / http://localhost:8465/ nocanon
ProxyPassReverse / http://localhost:8465/
</VirtualHost>

Die SSL-Parameter mit dem Pfaden zu Ihren Zertifkaten uns Schlüsseln würden in diesem Konfigurations-Beispiel in der Apache-globalen Datei /etc/letsencrypt/ssl-xyz.de.conf liegen.

== Hinweise zur Lizenzierung ==
Wenn Sie expecco ALM erworben haben, erhalten Sie einen Dongle und eine Lizenzdatei. Falls Sie expecco ALM evaluieren, erhalten Sie ausschließlich die Lizenzdatei. Die Lizenzdatei beinhaltet eine für Sie individuelle expecco ALM Lizenz. So sind zum Beispiel: Der Name Ihrer Firma, für Sie freigeschaltete Module oder die Gültigkeitsdauer in der Lizenz hinterlegt. Der Dongle muss (insofern Sie expecco ALM erworben haben) ständig mit dem Server, auf dem expecco ALM ausgeführt wird, verbunden sein. Falls Sie den Dongle während des Betriebs abziehen, wird expecco ALM seinen Dienst einstellen.

== Lizenz wechseln ==
[[Datei:ChangeAlmLicense.png|mini|Anhang 2]]
Falls Sie eine aktuelle expecco ALM Version haben, können Sie eine neue Lizenzdatei "expecco ALM Lizenz *.lic" über das Webinterface von expecco ALM einspielen. Betrachten Sie dazu den angehängten Screenshot (Anhang 2).

Fall Sie eine ältere expecco ALM Version haben, müssen Sie folgendermaßen vorgehen:
 - Da Sie expecco ALM später neustarten müssen, tätigen Sie entsprechende Vorsorgemaßnahmen (Bspw. Benutzer abmelden, Datenbank sichern usw.)
 - Melden Sie sich auf dem Computer, der expecco ALM betreibt an
 - Begeben Sie sich in folgendes Verzeichnis "C:\Windows\SysWOW64\config\systemprofile\AppData\Roaming\expecco_ALM" oder falls es sich um ein 32Bit Betriebssystem handelt "C:\Windows\system32\config\systemprofile\AppData\Roaming\expecco_ALM" und löschen Sie die Datei "expecco_ALM.lic"
 - Starten Sie den expecco ALM Service über den Windows-Service-Manager neu oder beenden Sie über den Windows-Task-Manager den Prozess "expecco_ALM.exe", in letzterem Fall wird der Windows-Service-Manager expecco ALM automatisch neustarten.
 - Nun können Sie das expecco ALM Webinterface aufrufen. Es wird eine Seite zum Installieren Ihrer expecco ALM Lizenz angezeigt (Anhang 1). Über "Lizenzdatei installieren" können Sie Ihre Lizenzdatei. auswählen. Nach dem expecco ALM Ihre Lizenzdatei akzeptiert hat, können Sie diese entfernen.

== Einbringen von expecco Floating-Lizenzen ==
Der Lizenzservice von expecco ALM vergibt verfügbare expecco Floating-Lizenzen aus einem bestimmten Pool. 
In diesen zunächst leeren Pool können von eXept erworbene expecco Floating-Lizenzen eingebracht werden.
 
Diese expecco Floating-Lizenzen erhalten Sie als Lizenzdatei(en) üblicherweise per E-Mail. 
Eine Lizenzdatei kann eine oder mehrere expecco Floating-Lizenzen auch für verschiedene Komponenten (Basissystem, Plugins und Erweiterungen) enthalten. 
Sie können auch jederzeit weitere expecco Floating-Lizenzen erwerben und in den Pool einbringen.
 
expecco Floating-Lizenzen werden immer spezifisch für eine expecco ALM Lizenz erstellt und sind nur mit dieser und deren Dongle nutzbar. 
Es ist also nicht notwendig solche Lizenzdateien unter Verschluss zu halten oder über eine sichere Verbindung auszutauschen. 
Allerdings sollten Sie den Dongle sicher aufbewahren bzw. Diebstahl vorbeugen.
 
Zur Einbringen einer expecco Floating-Lizenz öffnen Sie expecco ALM und melden Sie sich an. 
Jetzt navigieren Sie über die obere Hauptnavigationsleiste zum "Lizenzservice" Modul.
 
Sie befinden sich nun im Lizenzservice und Ihnen wird die Liste der installierten expecco Floating-Lizenzen angezeigt. 
Wechseln Sie zur Registerkarte "expecco Lizenzdateien". 
Navigieren Sie mithilfe des Navigationsmenüs auf der linken Seite zu "Hochladen/Upload". 
Hier können Sie nun durch ein einfaches Hochladen Ihrer expecco Floating-Lizenzen selbige in den Pool einbringen. 
In der zuvor genannte Liste werden nun die eben hochgeladenen expecco Floating-Lizenzen anzeigt. 
Diese sind von nun an auch von entfernten expecco Clients abrufbar. 
Sie können auch jederzeit weitere expecco Floating-Lizenzen erwerben und in den Pool einbringen.

== Lizenz Übersicht ==
Welche einzelnen expecco Floating-Lizenzen verfügbar oder vergeben sind, 
erfahren Sie indem Sie zur Registerkarte "expecco Lizenzen" wechseln. 
Insbesondere ist hieraus ersichtlich, welcher Rechner/Benutzer welche expecco Floating-Lizenz aktuell nutzt. 
Dies ist beispielsweise sinnvoll, wenn ein expecco Client seine Sitzung versehentlich nicht beendet hat, 
und andere Nutzer eine entsprechende Lizenz benötigen.

Installation

2025-07-09T08:31:49Z

Sv: /* Benötigte Linux Softwarepakete */

[[Installation/en#Additional_Packages_and_Frameworks| English Version]]

== Installation von expecco auf Windows ==

Sie erhalten eine E-Mail mit dem Link zu der expecco-Installationsdatei. Die Installationsdatei hat z.B. den Namen:

* expeccoSetup64-23.1.0.50.exe -> für die expecco-Basisinstallation

wobei hier 23.1.0 der Versionsnummer von expecco entspricht und 50 der Build-Nummer ("23.1.0.50" entspricht hier der Version zum Zeitpunkt der Erstellung dieses Dokuments - Sie werden mit Sicherheit eine andere Versionsnummer sehen).

Bitte laden Sie das Installationsprogramm auf Ihren Rechner.

=== Windows SmartScreen / Blockierte Ausführung ===

Führen Sie das Installationsprogramm für die expecco-Basisinstallation aus (''expeccoSetup64-***.exe'').

Es kann vorkommen, dass Ihr Anti-Virus-Programm wie bspw. der [https://de.wikipedia.org/wiki/SmartScreen-Filter], die Installation blockiert. Dies ist bei neuen oder Vorab-expecco-Versionen vermutlich damit begründet, dass Ihr Anti-Virus-Programm unsere Software noch nicht gut genug kennt. Bitte stellen Sie in dem Fall sicher, dass die Installationsdatei ausschließlich aus einer der folgenden Quellen heruntergeladen wurde https://exept.de/*, https://download.exept.de/*, https://cloud.exept.de/*. Wenn Sie sich sicher sind, dass die Installationsdatei von uns stammt, können Sie ohne Bedenken die Blockierung Ihres Anti-Virus-Programms ignorieren. Unsere Installationsprogramme sind auch mit einem Zertifikat der eXept Software AG signiert.

Die Installationsdatei für expecco sowie die expecco Programme sind mit dem digitalen Zertifikat von eXept Software AG signiert.

Im Falle vom [https://de.wikipedia.org/wiki/SmartScreen-Filter], gehen Sie bitte auf "Weitere Informationen" und dann auf "Trotzdem ausführen".

[[Bild:Windows_SmartScreen.png|300px|Report Settings]] [[Bild:Windows_SmartScreen_Trozdem_ausführen.png|300px|Report Settings]]

Falls Sie ein anderes Anti-Virus-Programm haben, informieren Sie sich bitte wie man dort die Blockierung ignorieren oder die Installationsdatei als Ausnahme definieren kann.

Folgen Sie dabei dem Installationsassistenten.
Sie können hier das Laufwerk und das Verzeichnis angeben, unter dem expecco installiert werden soll.
Außerdem können Sie die Komponenten angeben, die Sie installieren wollen.

Falls Sie Plugins für expecco lizenziert haben, können Sie bei der Installation die entsprechenden expecco-Plugins auswählen.
Angeboten werden alle Plugins - auch solche für die Sie keine Lizenzen erworben haben.
Falls Sie nicht lizenzierte Plugins installieren, ist deren Funktion in expecco nicht verfügbar und entsprechende Menu-Einträge entweder unsichtbar oder ausgegraut.
 Installierte, aber nicht lizenzierte Plugins sind erst dann verfügbar, wenn die dazu passenden Lizenzen (nach-)installiert wurden.
Ansonsten belegen Sie nur Platz auf der Festplatte.
Weitere Plugins können auch jederzeit nachträglich installiert werden. Auch können auch weitere Lizenzen jederzeit später erworben werden.

Nach der Installation finden Sie auf Ihrem Desktop das expecco-Symbol.
Über dieses Symbol können Sie expecco nun starten.
Beim erstmaligen Ausführen, erscheint ein Fenster, in dem eine Lizenz verlangt wird.
Je nachdem, ob Sie eine Einzellizenz oder eine Floating-Lizenz (per Lizenzserver) nutzen, müssen Sie die Lizenz entsprechend nachfolgender Beschreibung installieren.

=== Automatische Installation von expecco via Commandline (Windows) ===

Sie können expecco über die Kommandozeile, via Batchdatei oder ähnlichem installieren. Führen Sie dazu expecco wie folgt aus:
expeccoSetup-x.x.exe /S
Das "/S" steht für "''Silent''" und expecco installiert sich ohne GUI und ohne Fragen zu stellen.
Sie können optional auch ein spezifisches Installationsverzeichnis angeben:
expeccoSetup-x.x.exe /S /D="C:\Program Files (x86)\exept"
Damit expecco nach der Installation direkt starten kann, muss sichergestellt werden, dass eine Lizenz auf dem Zielrechner vorhanden ist. Hierfür kommen folgende Varianten in Frage.

'''Lizenz aus lokaler Lizenzdatei und Dongle''': 
Stecken Sie den Dongle in den Zielrechner. Kopieren Sie Ihre Lizenzdatei in Ihr Benutzerverzeichnis bspw. "<code>C:\Users\IhrBenutzername\</code>" unter dem Namen "<code>.expeccoLicense</code>", sodass die Datei "<code>C:\Users\IhrBenutzername\.expeccoLicense</code>" Ihrer Lizenzdatei entspricht.

'''Lizenz vom Lizenzserver''':
Hier müssen zunächst eine "Template" Lizenzdatei und "Template" expecco Einstellungen-Datei erstellt werden. Sie benötigen dafür ein laufendes expecco, welches mit Ihrem Lizenzserver verbunden ist. Starten Sie dieses expecco und konfigurieren Sie unter "''Extras''" → "''Einstellungen''" → "''Lizenzinstallation''" → "''Lizenz vom Lizenzserver''" Ihre "Template" Lizenzdatei. Diese sollte alle Plugins, die auf dem Zielrechner für die automatisierte expecco Installation über Commandline benötigt werden, enthalten. Fordern Sie diese Lizenz vom Lizenzserver an. Setzen Sie den Haken "Lizenzserver nutzen" und drücken Sie anschließend "Sichern". expecco hat nun die benötigten Template Dateien unter "<code>C:\Users\IhrBenutzername\AppData\Roaming\expecco</code>" angelegt. Kopieren Sie die "<code>.expeccoPreferences</code>" und die "<code>expeccoLicenseServerLicense</code>" Datei vor der automatischen expecco Installation in das entsprechende Verzeichnis auf Ihrem Zielrechner. expecco kann somit direkt nach der automatischen Installation starten.

=== Autostart von expecco ===

Öffnen Sie dazu mit der <kbd>Windows-Taste</KBD> + <KBD>"R"</KBD> ein Ausführungs-Fenster. Geben Sie dort "shell:startup" ein. Danach öffnet sich der Autostart-Ordner. Kopieren Sie die expecco-Verknüpfung vom Desktop in diesen Ordner. Nun wird expecco, nachdem sich dieser Benutzer angemeldet hat, automatisch gestartet. Folgend können Sie konfigurieren, dass sich dieser Benutzer automatisch anmeldet, wenn der Rechner angeschaltet wird. Drücken Sie dazu erneut <KBD>Windows-Taste</KBD> + <KBD>"R"</KBD>. Geben Sie nun "netplwiz" ein. Es öffnet sich der Benutzerkonten-Dialog. In diesem können Sie den Haken "Benutzer müssen Benutzernamen und Kennwort eingeben" abwählen. Diese Einstellung gilt nur für das Anmelden nachdem der Rechner hochgefahren ist.

Übrigens können diverse Parameter auf der [[Command Line Options|expecco-Kommandozeile]] angegeben werden. Hier sind insbesondere die Optionen [[Command Line Options#Startup|"--licenseFile"]], [[Command Line Options#Startup|"--licenseServer"]] und [[Command Line Options#Startup|"--licenseServerPort"]] zu erwähnen.

=== expecco Einstellungen vordefinieren ===

Es kann in bestimmten Fällen Sinn machen, die expecco Einstellungen für neue Windows-Benutzerkonten vorzudefinieren.
Z.B. könnte man die Adresse des Lizenzserver und die benötigten Pluginlizenzen vordefinieren.
Dies hätte den Vorteil, dass neue Benutzer direkt mit expecco loslegen können.

Gehen Sie zum Vordefinieren der expecco Einstellungen für neue Windows-Benutzerkonten folgendermaßen vor:
* starten Sie expecco auf einem bereits vorhandenen Benutzerkonto (kann auch ein anderer Windows Rechner sein)
* stellen Sie dessen expecco Einstellungen ("''Extras''" → "''Einstellungen''") wie zur Vorlage gewünscht ein und speichern Sie über "''Sichern''"
* navigieren Sie zu dem Verzeichnis "C:\Users\{IhrBenutzer}\AppData\Roaming\expecco\" und kopieren Sie die 2 Dateien ".expeccoPreferences" und "expeccoLicenseServerLicense"
* begeben Sie sich zum Zielrechner und erstellen Sie einen Ordner "expecco" unter "C:\Users\Default\AppData\Roaming\"
* fügen Sie die 2 kopierten Dateien auf dem Zielrechner unter "C:\Users\Default\AppData\Roaming\expecco\" ein

Jetzt werden alle neuen Windows-Benutzerkonten diese Einstellungen als Ausgangseinstellungen verwenden. Sie können diese Einstellungen auch bereits existierenden Windows-Benutzerkonten zuweisen. Hierfür fügen Sie die 2 Dateien in die entsprechenden Benutzerverzeichnisse auf dem Zielrechner "C:\Users\{ExistierenderBenutzer}\AppData\Roaming\expecco\" ein.

ACHTUNG: damit werden alle bereits getätigen Einstellungen der Benutzer überschrieben.

=== Update Installation von expecco (Windows) ===

Wie bei der Erstinstallation erhalten eine E-Mail mit dem Link zu den neuen expecco-Installationsdateien.
Bitte laden Sie die Installationsprogramme herunter.
Bei der Ausführung des Basis-Installationsprogramms "<code>expeccoSetup-xxx.exe</code>" erkennt expecco, dass es bereits installiert ist, und zeigt einen Dialog an, in dem Sie um eine Bestätigung gebeten werden, dass die alte expecco-Version deinstalliert werden darf.
Bestätigen Sie bitte diesen Dialog. Die alte expecco-Version wird mit allen Plugins deinstalliert.
Ihre Einstellungen, Lizenzdateien und Ihre Testsuiten bleiben erhalten.
Anschließend wird die neue expecco-Version wie bei der Erstinstallation (s.o.) installiert.

=== Lizenz installieren ===

Beim erstmaligen Ausführen erscheint ein Fenster, in dem eine Lizenz verlangt wird. Je nachdem, ob Sie eine Einzellizenz oder eine Floating-Lizenz (per Lizenzserver) nutzen, können Sie die Lizenz konfigurieren.

[[#Konfiguration der Einzellizenz | Konfiguration der Einzellizenz]]

[[#Konfiguration der Floating-Lizenz | Konfiguration der Floating-Lizenz]]

== Installation von expecco auf Linux ==

expecco läuft auf allen aktuellen Linux-Distributionen (Ubuntu, RedHat, Fedora, Oracle Linux, Debian, (Open-)SuSE, ...).

=== Benötigte Linux Softwarepakete ===

expecco läuft sowohl auf 32- als auch auf 64-bit Linux Systemen. Sie können expecco wahlweise als 64-bit-Version oder 32-bit-Version installieren.
Falls sie ein 64-bit Linux einsetzten (das ist mittlerweile der Standard) empfehlen wir die 64-bit expecco-Version. '''Die 32-bit Linux-Version liefern wir nur noch auf Anfrage aus.'''

Es wird eine glibc in der Version >= 2.14 benötigt.

Installieren Sie über Ihren Paketmanager Ihrer Linux-Distribution folgende Pakete:

* <code>libXinerama</code>
* <code>libxrandr</code>
* <code>libXft</code>
* <code>libusb</code>
* <code>unixODBC</code>
* <code>odbcinst</code>
* <code>libglib-2_0-0</code>
* <code>gnuplot</code> (optional - falls Plot/Graph Aktionen benötigt)

Diese Pakete hängen von weiteren Paketen ab, die der Paketmanager automatisch mit installiert.

In '''Ubuntu (ab 15.04)''' installieren Sie die Pakete mit dem Kommando:

<code>sudo apt-get update && sudo apt-get install -y \
libxinerama1 libxft2 libxrandr2 unixodbc odbcinst libusb-1.0.0</code>

In '''OpenSUSE (Leap 15.x)''' installieren Sie die Pakete mit:

<code>sudo zypper install unixODBC libXinerama1 libXrandr2 libXft2 libusb-0_1-4 libusb-1_0-0</code>

==== Installation von 32-bit expecco auf 64-bit Linux (nicht empfohlen!) ====

Diese Konfiguration empfehlen wir nicht. Nutzen Sie stattdessen besser die 64-bit expecco Version.
Falls Sie expecco-32-bit doch auf 64-bit-Linux installieren wollen, benötigen Sie die Pakete in der 32-bit Ausführung.

Es wird eine glibc in der Version >= 2.10 benötigt.

In Ubuntu 64bit (ab 15.04 64-bit) für ein 32-bit expecco installieren Sie die Pakete mit dem Kommando:

<code>sudo apt-get update && sudo apt-get install -y \
libxinerama1:i386 libxft2:i386 libxrandr2:i386 unixodbc:i386 odbcinst:i386 libusb-1.0.0:i386</code>

=== Installation von expecco (Linux) ===

Sie erhalten eine E-Mail mit dem Link zu der expecco-Installationsdatei. Die Installationsdatei hat z.B. den Namen:

* expecco-23.2.0.69.package

wobei hier 23.2.0 der Versionsnummer von expecco entspricht und 69 der Build-Nummer. Die Installationsdatei enthält das expecco-Basispaket sowie die Plugins.

Für die Installation benötigen Sie bei einer erstmaligen Installation außerdem noch das ''autopackage'' Paket. Sie können es hier herunterladen: https://download.exept.de/transfer/autopackage/x86_64/autopackage.tar.bz2. Entpacken Sie das Archive und installieren Sie dieses durch das Ausführen der INSTALL Datei im Root Verzeichnis des Archives. Sie werden ggf. gefragt ob die GUI Komponenten vom "Autopackage" herunter geladen und installiert werden sollen. Wählen Sie "NEIN" aus, da diese nicht benötigt werden und unter Umständen zu Fehlern führen können.

Laden Sie die expecco-Installationsdatei und ggf. ''autopackage.tar.bz2'' in dasselbe Verzeichnis auf Ihrem Rechner.

Sie können die Installation als Benutzer ''root'' oder als normaler Benutzer ausführen. Wenn Sie expecco als Benutzer ''root'' installieren, wird expecco im Verzeichnis ''/opt/expecco/bin'' installiert. Bei einer Installation als normaler Benutzer, wird expecco in Ihrem Home-Verzeichnis nach ''.local/bin'' installiert.

Führen Sie aus:
bash ./expecco-23.2.0.69.package

expecco wird daraufhin installiert, es erscheint folgende Ausgabe:
# Preparing package: expecco - Graphical Test Modeling
# Checking for required C library versions ... passed
This may take a moment, please wait ... done
# Installing package: expecco - Graphical Test Modeling (package 1 of 1)
# 100%[==================================================] Extracting
# Copying files to /opt/expecco/plugin
# 100%[==================================================] Copying
# Copying files to /opt/expecco/packages/exept/technologyBridge
# Copying files to /opt/expecco/packages/exept/technologyBridge/javaBridge
# Copying files to /opt/expecco/packages/exept/technologyBridge/javaBridge/javaBridge_Server_Client
# 100%[==================================================] Copying
# Copying files to /opt/expecco/packages/stx/libsnmp
# Copying files to /opt/expecco/packages/stx/libsnmp/net-snmp-5.7.2/mibs
# 100%[==================================================] Copying
# Copying files to /opt/expecco/testsuites/libraries
# 100%[==================================================] Copying
# Copying files to /opt/expecco/bin
# 100%[==================================================] Copying
# Copying files to /opt/expecco/lib
# 100%[==================================================] Copying
# Copying files to /opt/expecco/packages/exept/expecco/doc
# 100%[==================================================] Copying
# Copying files to /opt/expecco/testsuites/libraries
# 100%[==================================================] Copying
# Copying files to /opt/expecco/testsuites/examples
# 100%[==================================================] Copying
# Copying files to /opt/expecco/packages/exept/expecco/reportGenerator/tools
# Copying files to /opt/expecco/packages/exept/pdf/afm
# 100%[==================================================] Copying
# Installing USB Dongle access...
# Updating package database...
The following package was successfully installed:
* expecco - Graphical Test Modeling
This installation used 478.74 MiB (502.00 MB) of disk space.
Remove this package by running package remove expecco from the command line.

=== Spezielle Installations-Optionen ===

Sie können das Verzeichnis, in das expecco installiert wird, wie folgt festlegen:

bash expecco-23.2.0.69.package
Installation als root nach /opt/expecco (Starten mit: /opt/expecco/bin/expecco)

bash expecco-23.2.0.69.package --prefix /opt/expecco-23.2
Installation als root nach /opt/expecco-23.2 (Starten mit: /opt/expecco-23.2/bin/expecco)

bash expecco-23.2.0.69.package --local-only
Installation als Benutzer nach $HOME/.local (Starten mit ~/.local/bin/expecco)

bash expecco-23.2.0.69.package --local-only --prefix ~/expecco
Installation als Benutzer nach $HOME/expecco (Starten mit ~/expecco/bin/expecco)

=== Update Installation von expecco (Linux) ===

Wie bei der Erstinstallation erhalten eine E-Mail mit dem Link zu der neuen expecco-Installationsdatei.
Bitte laden Sie das Installationsprogramme herunter. Bei der Ausführung des Installationsprogramms ''bash expecco-***.package'' erkennt expecco, dass eine andere Version bereits installiert wurde. Die alte expecco-Version wird mit allen Plugins automatisch deinstalliert. Ihre Einstellungen, Lizenzdateien und Ihre Testsuiten bleiben erhalten. Anschließend wird die neue expecco-Version wie bei der Erstinstallation (s.o.) installiert.

=== Deinstallieren ===

autopackage uninstall expecco

=== Lizenz installieren ===

Installieren Sie die Lizenz wie im nächsten Abschnitt beschrieben.

== Installation von expecco auf OS X ==

Achtung: die OS X-Version ist z.Z. im Beta Test und auf Anfrage verfügbar.

=== Benötigte macOS Softwarepakete ===

expecco läuft auf 64-bit x64_64 mac OS X Systemen (eine Version für ältere 32bit Maschinen ist nur noch auf Anfrage erhältlich; beachten Sie, dass die neueren OS X Versionen 32bit Programme nicht mehr unterstützen).
Es wird mindestens OS X 10.6 benötigt.

expecco benötigt XQuartz. Dieses sollten Sie vorher vom Apple Store oder [https://www.xquartz.org/ xquartz.org] installieren, falls nicht bereits vorinstalliert (kostenlos).

=== Installation von expecco (OS X) ===

Sie erhalten eine E-Mail mit dem Link zu der expecco-Installationsdatei. Die Installationsdatei hat z.B. den Namen:

* expecco-2.11.0.1.dmg

wobei hier 2.11.0 der Versionsnummer von expecco entspricht und 1 der Build-Nummer. Die Installationsdatei enthält das expecco-Basispaket sowie die Plugins.

Zur Installation öffnen Sie die "<code>dmg</code>"-Datei und verschieben "<code>expecco.app</code>" in den "<code>Application</code>"-Ordner (oder Ihren privaten "<code>Application</code>"-Ordner, oder jeden beliebigen anderen Ordner).

=== Deinstallation von expecco (OS X) ===
Sämtliche Dateien von expecco, mit Ausnahme Ihrer eigenen Suiten und Einstellungen sind im expecco.app Ordner. Löschen Sie diesen Ordner (und entleeren den Papierkorb) um expecco zu deinstallieren.
Ihre eigenen Einstellungen befinden sich im Homeverzeichnis unter ".expecco"; Ihre Suiten sind im Documentsordner, falls nicht explizit an anderer Stelle gespeichert.

== Konfiguration der Lizenz ==

Beim erstmaligen Ausführen erscheint ein Fenster, in dem eine Lizenz verlangt wird. Falls Sie bereits eine Lizenz installiert haben und diese wechseln möchten können Sie den selben Dialog unter "''Extras''" → "''Einstellungen''" → "''Lizenzinstallation''" öffnen, allerdings müssen Sie in diesem Fall nach dem Wechseln der Lizenz expecco neu starten.

Fall Sie expecco auf einem Computer ohne GUI installiert haben, kann das zuvor erwähnte Fenster nicht geöffnet werden. In dem Fall müssen Sie expecco auch auf einem Computer mit GUI installieren und dort den Dialog ausfüllen. Danach kopieren Sie die Settingsdatei "<code>~/.expecco/.expeccoPreferences</code>" oder "<code>C:\users\IhrBenutzer\AppData\Roaming\expecco\.expeccoPreferences</code>" und die Lizenzdatei "<code>~/.expecco/expeccoLicenseServerLicense</code>" oder "<code>C:\users\IhrBenutzer\AppData\Roaming\expecco\expeccoLicenseServerLicense</code>" auf den Computer ohne GUI.

[[#Konfiguration der Einzellizenz | Konfiguration der Einzellizenz]]

[[#Konfiguration der Floating-Lizenz | Konfiguration der Floating-Lizenz]]

[[#Auslösen einer Floating-Lizenz | Auslösen einer Floating-Lizenz]]

=== Konfiguration der Einzellizenz ===

Einzellizenzen werden üblicherweise mit einem USB-Dongle genutzt.
Ausnahmsweise können auch zeitlich limitierte Einzellizenzen ohne Dongle verwendet werden (sog. "''Demo Lizenz''").
In beiden Fällen erhalten Sie eine Lizenzdatei.
Lizenzdateien und Dongle müssen jeweils zusammenpassen, wobei eine Lizenzdatei auch zu mehreren Dongles desselben Kunden passen kann.

# falls Sie einen Dongle erhalten haben, stecken Sie ihn in einen freien USB-Port in Ihrem Rechner.
# Speichern Sie die Lizenzdatei auf Ihrem Rechner
# Ziehen Sie dann entweder die Datei mit der Maus aus dem Windows-Explorer in den Lizenzdialog, oder Sie wählen im Lizenzdialog Ihre Lizenzdatei direkt aus.
# Sie werden aufgefordert, expecco neu zu starten. Nach dem Neustart können Sie expecco nutzen.

Lizenzdateien ohne Dongle sind zeitlich beschränkt.
Wenn Sie versehentlich den expecco-Dongle nicht in Ihren Rechner eingesteckt haben und expecco starten, erhalten Sie einen Hinweis, dass die Lizenz abgelaufen sei.
Sobald Sie den Dongle einstecken (bevor Sie expecco starten), erscheint dieser Hinweis beim Start von expecco nicht mehr.

Solange Sie mit expecco arbeiten, wird überwacht, ob der Dongle vorhanden ist.
Wenn Sie den Dongle währenddessen aus Ihrem Rechner entfernen, erhalten Sie einen Hinweis und können keine Tests mehr ausführen oder verändern.
Sie können allerdings die gerade bearbeitete Testsuite noch abspeichern, so dass keine Änderungen verloren gehen.

=== Konfiguration der Floating-Lizenz ===

Um eine Floating-Lizenz zu nutzen, benötigen Sie einen expecco-Lizenzserver. Diesen (bzw. den Downloadlink) erhalten Sie von uns mit den Floatinglizenzen. Der Lizenzserver ist eine HTTP-Serviceanwendung, die auf einem beliebigen Rechner in einer Cloud oder Ihrer Firma oder Abteilung installiert wird. Sie läuft ohne eigenes Fenster, und wird über einen beliebigen WebBrowser bedient.

Der Lizenzserver ist unter einem Rechnername bzw. IP-Adresse und einer Portnummer zu erreichen.
Der Administrator des Lizenzservers kann Ihnen diese Informationen geben, falls er eine andere als die default-Portnummer konfiguriert hat.
Es muss sichergestellt sein, dass eine TCP-Verbindung zum entsprechenden Port im Lizenzserver aufgebaut werden kann.
Router und Firewalls sind gegebenenfalls entsprechend zu konfigurieren bzw. Ports freizuschalten.

Beim Start von expecco öffnet sich der Lizenzdialog.
Wählen Sie hier die Lizenzserver-Kachel aus.
Tragen Sie den Rechnernamen bzw. die IP-Adresse sowie die Portnummer des Lizenzservers ein.
Im allgemeinen kann die vorgeschlagene default Portnummer unverändert übernommen werden.
Lediglich in Netzwerken, bei denen nur bestimmte Ports durch Firewalls oder Router durchgeschaltet werden ist es u.U. notwendig, eine andere Portnummer zu verwenden.
Der Administrator des Lizenzservers kann Ihnen in diesem Fall diese Informationen geben

Sie können jetzt auswählen, welche expecco-Ausprägung Sie verwenden wollen: ''expecco-developer'' oder ''expecco-runtime''.
Über die Schaltfläche "''Plugin-Liste vom Server aktualisieren''" erhalten Sie die verfügbaren Plugins (bzw. Plugins für die noch Floating-Lizenzen verfügbar sind).
Wählen Sie die Plugins aus, die Sie für Ihre Tests benötigen.
Von den meisten Plugins benötigen Sie nur eine Lizenz.
Einzelne Plugins können für auf mehrere Rechner verteilte Tests mehr als eine Lizenz von einem Plugin benötigen - Sie können das für derartige Plugins angeben.
Im Dialog wird angezeigt, wie viele Lizenzen für ein bestimmtes Plugin auf dem Lizenzserver momentan noch zur Verfügung stehen.
Per Tooltip können Sie auch in Erfahrung bringen, wie viele Lizenzen generell vorhanden sind.
Die Differenz sind die momentan von anderen Benutzern verwendeten Lizenzen.

Über die Schaltfläche "''Lizenzdatei installieren''" werden die Lizenzen vom Lizenzserver abonniert.
Starten Sie jetzt expecco neu, damit die lizenzierten Plugins geladen werden.

Wenn expecco beendet wird, werden alle Lizenzen wieder an den Lizenzserver zurück gegeben.
Expecco erneuert regelmäßig die Lizenzen vom Lizenzserver.
Wenn der Lizenzserver über einen gewissen Zeitraum nicht mehr erreichbar sein sollte (ca. 15 Minuten), wird expecco gesperrt, so dass keine Tests mehr ausgeführt oder verändert werden können. Geänderte Testsuiten können aber noch abgespeichert werden.

Wenn expecco nicht regulär beendet wurde, z.B. wenn der Rechner einfach ausgeschaltet wird, fallen die Lizenzen nach diesem Zeitraum an den Lizenzserver zurück und können dann von anderen Benutzern genutzt werden.

expecco merkt sich, welche Lizenzen zuletzt abonniert wurden.
Wenn expecco gestartet wird, versucht es, die zuletzt abonnierten Lizenzen wieder zu erhalten.
Sollte das nicht möglich sein, da alle Lizenzen momentan vergeben sind, erscheint der Lizenzdialog, in dem die nicht oder nur teilweise erhaltenen Lizenzen rot unterlegt sind.

Wenn Sie neue Lizenzen benötigen oder bisher verwendete Lizenzen nicht mehr benötigen, können Sie die anzufordernden Lizenzen jederzeit über den Lizenzdialog anpassen.
Sie erreichen ihn über das Menü "''Extras''" → "''Einstellungen''" → "''Lizenzinstallation''".

=== Auslösen einer Floating-Lizenz ===

Floatinglizenzen können auch ohne bestehende Verbindung zum Lizenzserver ausgelöst werden (sog. "''road warrior'' Lizenzen"). Dies ermöglicht es Ihnen, auch zuhause, bei Kunden oder in isolierten Labors mit expecco zu arbeiten, ohne dass dafür ein Dongle benötigt wird.

'''Verfügbar ab expecco Version 2.10.x.x'''

Auch wenn Ihr expecco keine Netzwerkverbindung hat, ist es möglich expecco mit einer Floating-Lizenz zu betreiben. Die Lizenz für expecco wird für eine bestimmte Zeitspanne ausgelöst. Nachdem diese Zeitspanne verstrichen ist, wird die ausgelöste Lizenz automatisch wieder zurückgegeben (eingegliedert). Bitte beachten Sie, dass es '''keine Möglichkeit gibt, eine ausgelöste Lizenz vor ihrem Ablauf wieder zurückzugeben!'''

Hierfür brauchen Sie einen Lizenzservice (expecco ALM), aus welchem die Floating-Lizenz ausgelöst wird.

Zum Auslösen einer Floating-Lizenz starten Sie expecco und rufen Sie den Lizenzdialog unter "''Extras''" → "''Einstellungen''" → "''Lizenzinstallation''" auf (beim erstmaligem Start erscheint dieser automatisch) und navigieren Sie in den Reiter "Ausgelöste Floating-Lizenz".

Dort haben Sie folgende Möglichkeiten:
==== Eine Anfrage zum Auslösen einer Floating-Lizenz erstellen ====
Stellen Sie sich Ihre gewünschte Lizenz zusammen. Definieren Sie den Typ (Runtime / Pro), die Plugins und wie lange Sie die Lizenz auslösen möchten. Sie können Ihre Anfrage dann entweder in eine Datei speichern oder in die Zwischenablage legen.

Rufen Sie nun das Web-Interface des Lizenzservices (expecco ALM) in einem Webbrowser auf. Navigieren Sie in expecco ALM zu "''Lizenzservice''" → "''expecco Lizenzen''" → "''Lizenz auslösen''". Dort können Sie dann Ihre Anfrage entweder über Datei hochladen oder aus der Zwischenablage in das freie Feld einfügen.

Nach dem erfolgreichen Einspielen Ihrer Anfrage wird Ihnen Ihre Anfrage zur Gegenprüfung im Detail angezeigt. Sie können hier die Dauer der Auslösung ggf. erneut anpassen. Über den Knopf "Auslösen bestätigen" wird die Lizenz endgültig ausgelöst. Danach ist diese Lizenz bis zum Ablauf der Dauer ausschließlich für das expecco, von welchem die Anfrage erstellt wurde reserviert. Ihnen wird anschließend der Bestätigungsschlüssel angezeigt. Diesen können Sie wiederum als Datei speichern oder über Rechtsklick "Kopieren" in die Zwischenablage legen.

Jetzt müssen Sie diesen Bestätigungsschlüssel an expecco übertragen (über USB-Stick, Zuruf, Telefon usw.) und eingeben oder die Datei auswählen.

==== Eine bereits ausgelöste Floating-Lizenz in Betrieb nehmen ====
Falls Sie expecco aus Versehen während dem Prozess des Auslösens geschlossen haben oder der Prozess durch etwas ähnlich unterbrochen wurde, ist die ausgelöste Lizenz nicht verloren. Sie können diese Lizenz anhand Ihrer Anfrage und zugehörigem Bestätigungsschlüssel jederzeit in expecco aktivieren.

Öffnen Sie dazu den Lizenzservice (expecco ALM) und navigieren Sie nach "''Lizenzservice''" → "''expecco Lizenzen''" → "''Im Einsatz''". Suchen Sie in dieser Liste nach einer passenden Lizenz. Eine passende Lizenz erkennen Sie bspw. an der Spalte "Rechnername", diese Spalte sollte mit dem Rechnernamen auf dem expecco installiert ist übereinstimmen. Übertragen Sie die Anfrage sowie den Bestätigungsschlüssel aus den Spalten "Auslöse-Anfrage-Datei" und "Auslösungsschlüssel" zu expecco.

In expecco müssen Sie die Auslöse-Anfrage-Datei auswählen und diese dann mit dem Bestätigungsschlüssel aktivieren.

==== Die aktuell verwendete ausgelöste Floating-Lizenz verlängern ====

Das Verlängern einer ausgelösten Floating-Lizenz ist nur möglich, solange diese noch gültig ist. Nach dem Ablauf einer ausgelösten Lizenz wird diese im Lizenzserver gelöscht und Sie müssen diese durch eine neue Anfrage erneuern (i.e. eine neue Lizenz auslösen).

Öffnen Sie dazu den Lizenzservice (expecco ALM) und navigieren Sie nach "''Lizenzservice''" → "''expecco Lizenzen''" → "''Im Einsatz''". Suchen Sie in dieser Liste nach einer passenden Lizenz. Eine passende Lizenz erkennen Sie bspw. an der Spalte "Rechnername". Diese Spalte sollte mit dem Rechnernamen, auf dem expecco installiert ist, übereinstimmen.

Klicken Sie nun auf "Verlängern". Sie werden automatisch auf die Seite "Lizenz verlängern" weitergeleitet. Ihre Lizenz ist bereits vorselektiert. Sie können nun das gewünschte Datum eingeben. Danach wird Ihnen ein neuer Bestätigungsschlüssel angezeigt, diesen müssen Sie in expecco eingeben.

=== Änderung des Lizenztyps nach der Installation ===

Über das Menü "''Extras''" → "''Einstellungen''" → "''Lizenzinstallation''" können Sie die Lizenz nachträglich ändern.

'''Die Änderung des Lizenztyps werden permanent gespeichert, wenn Sie die Einstellung mit der Schaltfläche "Sichern" abspeichern.'''

== Weitere Hilfspakete und Frameworks ==

Die Basisinstallation wie oben beschrieben beinhaltet bereits die meisten normalerweise benötigten Komponenten. Abhängig von später durchzuführenden Tests und benötigter Software können (sollten) weitere Pakete ebenfalls installiert werden. Hinweise dazu finden Sie im Dokument: [[Installing_additional_Frameworks/en | "Installing additional Frameworks"]].

Wir empfehlen folgende Pakete:
* [[Installing_additional_Frameworks/en#Java_Installation_.28for_Groovy_Actions.2C_Web-_and_Mobile_Testing.29|Java Runtime or JDK]]
* [[Installing_additional_Frameworks/en#Python_Installation_.28for_Python_Actions.29|Python]]
* [[Installing_additional_Frameworks/en#OCR_.28Optical_Character_Recognition.29|Tesseract]] falls Sie OCR (Optical Character Recognition) zum Extrahieren von Texten aus Bildern und Bildschirmabzügen benötigen.

Ausserdem sinnvoll (aber seltener benötigt):
* [[Installing_additional_Frameworks/en#Node_Installation_.28for_Node.js_Actions.29|Node]]

Falls Sie Aktionen in C or C++ schreiben wollen (müssen):
* [[Installing_additional_Frameworks/en#C_Compiler_Toolchain_Installation_.28for_C-Actions.29|C Compiler Toolchain]]

== Patches und Aktualisierungen ==

Exept stellt auch zwischen zwei Major Releases zu Verfügung in unregelmäßigen Abständen oder auf Anfrage Patches und Erweiterungen.

Patches sind versionsabhängig; d.h. ein Patch für expecco Version 23.1 ist nicht für andere Versionen zu verwenden.
Normalerweise beinhaltet jede neue Major Release (z.B. 24.1) alle Patches aller Vorgängerversionen.
Oft sogar mehr Funktionalität. Alte Patches sollten daher nicht in neuere Versionen eingespielt werden,
und expecco lehnt auch solche Patches ab. Es besteht also keine Gefahr, dass diese aus Versehen eingespielt werden.

Die Patches kommen in Dateien paarweise: eine ".expeccoPatch" und eine ".info" Datei.
Letztere beinhaltet eine textuelle Beschreibung; erstere den eigentlichen Patch.
Die Patches sind signiert, und expecco wird nur patch Dateien welche von exept signiert sind akzeptieren.

Die patch Dateien können auf mehrere Arten sowohl manuell als auch automatisch heruntergeladen und eingespielt werden.
Sie befinden sich physikalisch auf dem download host von exept, unter "http://dowloads.exept.de" und "ftp://ftp.exept.de/downloads".

=== Automatisch vom Exept Download Server ===

Wenn sie Zugriff aufs Internet mit http (port80) oder https (port 443) haben,
gehen sie zu "Extras" - "Einstellungen" - "Software Aktualisierung".
Und verifizieren die Einstellungen zu "Patch Server".
Zum Test der Verbindung klicken sie auf "Jetzt nach Updates suchen".

Sie können oben auswählen, wann und wie oft expecco nach Updates schauen soll.

=== Automatisch von einem hauseigenen Download Server ===

Falls ihr Testrechner keinen Zugriff aufs Internet hat, aber ein anderer Rechner im Hausnetz erreichbar ist, können sie die Patches auch wie unten beschrieben auf diese Maschine herunterladen und von ihren Testrechnern die Patches dort abholen.
Dies hat den Vorteil, dass der download nur einmal durchgeführt werden muss, und sie selbst Kontrolle über die Patches haben.

Gehen sie dazu wie oben beschrieben zum Einstellungsdialog, und geben den Namen und Pfad ihres Servers ein. Dort sollte dann ein Dateiservice mit unten beschriebener Dateistruktur zu finden sein (z.B. ein entsprechen aufgesetzter apache Server).

=== Automatisch von einem hauseigenen Lizenz Server ===

Wenn Sie keinen apache Server aufsetzen wollen oder können, aber einen Lizenzserver verwenden, können sie die patches auch auf dessen Rechner unter einem beliebigen Verzeichnis ablegen und den Lizenzserver entsprechend konfigurieren.

Im Lizenzserver (AIDYMO) gehen sie zu den "Einstellungen" - "System", und finden unten in der Maske unter "Sonstige" eine Checkbox "Patches Service". Schalten sie diese Box ein, und geben darunter den Pfad zu dem patches Verzeichnis (auf dem Rechner des Lizenzservers).
Die Orderstruktur darunter entspricht der unten beschriebenen unter "expecco". I.e. "<versionsNr>/patches/..."

=== Manuell ===

Falls ihr Testrechner isoliert vom Internet oder dem Hausnetz arbeitet (z.B. in einem Cleanroom oder Prüfstand),
müssen die Patches zunächst auf den Rechner gebracht werden. Dies kann z.B. über ein Medium (USB-Stick) oder ein Netzlaufwerk erfolgen.

Unter dem jeweiligen Hauptverzeichnis (siehe oben) befindet sich ein Ordner per Release, und darunter die patch- und info Dateien.
Also z.B.:
https://download/expecco/23.2.0/patches
0001_fix1.expeccoPatch
0001_fix1.info
0002_feature1.expeccoPatch
0002_feature1.info
https://download/expecco/24.1.0/patches
0001_fix2.expeccoPatch
0001_fix2.info
usw.

Falls der automatische update versagt, können Sie die Dateien als fallback im Browser herunterladen (sichern als),
in einem Ordner sammeln und wie unten beschrieben manuell einspielen.

Falls es sich um einen Individualpatch für Sie persönlich handelt, kann er ihnen auch per email zugesandt, oder in AIDYMO als Anhang übergeben werden.

Bringen sie dazu die ".expeccoPatch" Dateien auf den Testhost (z.B. in ein Temp Verzeichnis), und
wählen im "Extras" -> "Maintenance" -> "Install Patch from File".
Im geöffneten Dialog wählen Sie die entsprechen(n) Datei(en) an und bestätigen sie.

Diesen Vorgang müssen Sie nur einmal durchführen; mit jedem Neustart werden die Patches automatisch neu installiert.
Die temporären Dateien können sie nach der Installation löschen; sie werden nicht mehr gebraucht.

Hauptseite

2025-06-23T10:18:38Z

Sv:

[[Hauptseite/en|English Version]]

Klicken Sie links auf ''"Letzte Änderungen"'' ("Recent changes") um die neuesten Einträge in der Dokumentation zu sehen. Sie sehen dann meist, woran unsere Entwickler gerade vornehmlich arbeiten.

<h2>expecco</h2>

<div style="display:flex; flex-wrap:wrap; padding:0; white-space:nowrap">
<div style="background-color:#ecf0fe; margin:12px 8px 0 0; flex:1 0 auto">

[[Datei:Icon_Landingpage.png|30px]]Für Einsteiger<hr>

<ul style="font-size:0.8em; padding:0.7em 1em 1em 2.4em">


<li>[https://doc.expecco.de/w2.x/index.php?title=Was_ist_expecco%3F Allgemeine Informationen]</li>
<li>[[Expecco Usecases|Einsatzbereiche]]</li>
<li>[[Features|expecco Feature-List]]</li>
<li>[[Tutorials]]</li>
<li>[[usageHints/en|Hinweise zur Bedienung]]</li>
<li>[[Glossary|Begriffserklärung]] (Glossar)</li>

<li>[[FAQ]]</li>
</ul>
</div>

<div style="background-color:#ecf0fe; margin:12px 8px 0 0; flex:1 0 auto">

[[Datei:Icon_Landingpage5.png|30px]]Installation<hr>

<ul style="font-size:0.8em; padding:0.7em 1em 1em 2.4em">
<li>[[Installation]]</li>
<li>[[Installing additional Frameworks/en| Installation zusätzlicher Tools (Node, Python, ...)]]</li>
<li>[[Personal Settings|Persönliche Einstellungen]]</li>
<li>[[Configuration & Setup|Konfiguration]]</li>
<li>[[Anbindung expecco ALM]]</li>
<li>[[SAP_Testing|Anbindung expecco an SAP]]</li>
<li>[[Spezifische Anpassung]]</li>
<li>[[expecco UI]]</li>
<li>[[Expecco_Remote_Control_App|expecco Mobile Remote App]]</li>
<li>[[Probleme & Fehler]]</li>
</ul>
</div>

<div style="background-color:#ecf0fe; margin:12px 8px 0 0; flex:1 0 auto">

[[Datei:Icon_Landingpage4.png|30px]]Werkzeuge<hr>

<ul style="font-size:0.8em; padding:0.7em 1em 1em 2.4em">
<li>[[API von Elementaraktionen]]</li>
<li>[[Debugger]]</li>
<li>[[Editoren]]</li>
<li>[[Standard Libraries/Bibliotheken]]</li>
<li>[[Weitere Werkzeuge]]</li>
<li>[[Weitere Funktionen]]</li>
</ul>
</div>

<div style="background-color:#ecf0fe; margin:12px 8px 0 0; flex:1 0 auto">

[[Datei:Icon_Landingpage6.png|30px]]Reportgenerierung<hr>

<ul style="font-size:0.8em; padding:0.7em 1em 1em 2.4em">
<li>[[Report Generation|Reportgenerierung]]</li>
<li>[[Errors during Execution|Fehler während der Ausführung]]</li>
<li>[[Secret Strings|Geheime Zeichenketten und Passwörter]]</li>
</ul>
</div>

<div style="background-color:#ecf0fe; margin:12px 8px 0 0; flex:1 0 auto">

[[Datei:Erweiterung_plugin.png|30px]]Erweiterungen (Plugins)<hr>

<ul style="font-size:0.8em; padding:0.7em 1em 1em 2.4em">
<li>[[GUI Testing]]
<ul>
<li>[[Java GUI Plugins|Java Swing/FX/SWT UI Testing]]</li>
<li>[[Mobile Testing Plugin|Mobile Testing auf Android und iOS]]</li>
<li>[[WindowsAutomation Reference 2.0|UI Testing mit der Windows Automation Library]]</li>
<li>[[Selenium_WebDriver_Plugin|Web Testing mit Selenium WebDriver]]</li>
<li>[[VNC_Plugin_Reference|VNC UI Testing]]</li>
<li>[[GUI Testing|Weitere GUI Testing Plugins]]</li>
</ul>
</li>
<li>[[Schnittstellen zum SUT]]</li>
<li>[[ManualTest]]</li>
<li>Produktivität
<ul>
<li>[[GIT Plugin]]</li>
<li>[[HG Plugin (Mercurial)]]</li>
<li>[[CVS Plugin]]</li>
<li>[[Anbindung expecco ALM | expeccoALM Schnittstelle]]</li>
</ul>
</li>
<li>[[Weitere Plugins]]</li>
</ul>
</div>

<div style="background-color:#ecf0fe; margin:12px 8px 0 0; flex:1 0 auto">

[[Datei:Icon_Landingpage3.png|30px]]Elemente der Testsuite<hr>

<ul style="font-size:0.8em; padding:0.7em 1em 1em 2.4em">
<li>[[Tree Elements|Tree Elemente]]</li>
<li>[[Folder Element|Ordner]]</li>
<li>[[Testplan Element]]</li>
<li>[[Aktionen/Aktionsblöcke]]</li>
<li>[[Datatype Element|Datentyp Element]]</li>
<li>[[Inventory Element]]</li>
<li>[[Skill Element]]</li>
<li>[[Resource Element|Ressource Element]]</li>
<li>[[Attachment Element|Anhänge]]</li>
<li>[[ReportTemplate Element|Report Templates]]</li>
</ul>
</div>

<div style="background-color:#ecf0fe; margin:12px 8px 0 0; flex:1 0 auto">

[[Datei:Icon_Landingpage3.png|30px]]API Referenz (Elementarbausteine)<hr>

<ul style="font-size:0.8em; padding:0.7em 1em 1em 2.4em">
<li>[[API von Elementaraktionen|Übersicht]]</li>
<li>[[Expecco API#JavaScript_and_Smalltalk_Elementary_Blocks|Smalltalk & JavaScript]]</li>
<li>[[Expecco API#Groovy_Elementary_Blocks|Groovy]]</li>
<li>[[Expecco_API#Node.js_.28Bridged.29_Elementary_Blocks|NodeJS]]</li>
<li>[[Expecco_API#Bridged_Python_Elementary_Blocks|Python]]</li>
<li>[[Expecco_API#Bridged_Ruby_Elementary_Blocks|Ruby]]</li>
<li>[[Expecco_API#Bridged_C_Elementary_Blocks|C]]</li>
<li>[[Expecco API#VisualBasic_Elementary_Blocks|VisualBasic ]]</li>
<li>[[Expecco Scripting API|Shell und Script Languages]]</li>
</ul>
</div>

<div style="background-color:#ecf0fe; margin:12px 8px 0 0; flex:1 0 auto">

[[Datei:Diagramm.png|30px]]Diagramm - Elemente<hr>

<ul style="font-size:0.8em; padding:0.7em 1em 1em 2.4em">
<li>[[DiagramElements-Step|Schritt]]</li>
<li>[[Pins (Ein - Ausgänge)]]</li>
<li>[[Code Ausführung]]</li>
<li>[[DiagramElements-Connection|Verbindung]]</li>
<li>[[DiagramElements-Pin|Pin Beschreibung]]</li>
<li>[[DiagramElements-Annotation|Notiz]]</li>
<li>[[DiagramElements-Probe|Messfühler]]</li>
</ul>
</div>

<div style="background-color:#ecf0fe; margin:12px 8px 0 0; flex:1 0 auto">

[[Datei:Refresh.png|30px]]Sonstiges<hr>

<ul style="font-size:0.8em; padding:0.7em 1em 1em 2.4em">
<li>[[Release Notes 25.x]]</li>
<li>[[Release Notes 24.x]]</li>
<li>[[Release Notes 23.x]]</li>
<li>[[Release Notes 22.x]]</li>
<li>[[Release Notes 21.x]]</li>
<li>[[Release Notes 20.x]]</li>
<li>[[Release Notes 19.x]]</li>
<li>[[Release Notes 18.x]]</li>
<li>[[Release Notes 2.x]]</li>
<li>[[Release Notes 1.x]]</li>
<li>[[Future releases expecco|Zukünftige Releases]]</li>
<li>[[Smalltalk]]</li>
</ul>
</div>

<div style="background-color:#ecf0fe; margin:12px 8px 0 0; flex:1 0 auto">

[[Datei:Beispiele_icon.png|30px]]Beispiele<hr>
Sie haben Fragen, wie ein Projekt aussieht?<hr>

<ul style="font-size:0.8em; padding:0.7em 1em 1em 2.4em">
 
<li>[[Beispiele | Hier finden Sie weitere Anwendungsbeispiele.]]</li>
<li>[[Expecco Code Snippets/en | Codeschnipsel]]</li>
</ul>
</div>

<div style="background-color:#ecf0fe; margin:12px 8px 0 0; flex:1 0 auto">

[[Datei:Beispiele_icon.png|30px]]Unterstützung weiterer Qualitätsmanagement Tools<hr>

<ul style="font-size:0.8em; padding:0.7em 1em 1em 2.4em">
<li>[[Jira_Plugin_Reference|Jira]]</li>
<li>[[PolarionPlugin_Reference|Polarion]]</li>
<li>[[Aqua_Plugin_Reference|Aqua]]</li>
<li>[[Starting_expecco_via_Command_Line#Integration_with_Jenkins|Jenkins Integration]]</li>

</ul>
</div>

</div>

<h2 style="clear:left">expecco ALM</h2>

<div style="display:flex; flex-wrap:wrap; padding:0; white-space:nowrap">
<div style="background-color:#ecf0fe; margin:12px 8px 0 0; flex:1 0 auto">

[[Datei:Sonstiges-Info.png|30px]]Allgemein<hr>

<ul style="font-size:0.8em; padding:0.7em 1em 1em 2.4em">
<li>[[Was ist expecco ALM?]]</li>
<li>[[Was ist der expecco Lizenzserver?]]</li>
<li>[[Anbindung expecco ALM]]</li>
<li>[[Rollen und Rechte]]</li>
<li>[[Filter]]</li>
<li>[[FAQ expeccoALM/en | FAQ]]</li>
</ul>
</div>

<div style="background-color:#ecf0fe; margin:12px 8px 0 0; flex:1 0 auto">

[[Datei:Icon_Landingpage5.png|30px]]Installation/Einrichten<hr>

<ul style="font-size:0.8em; padding:0.7em 1em 1em 2.4em">
<li>[[expecco ALM Installation|Installation]]</li>
<li>[[expecco ALM Installation Patches|expecco ALM Installation Patches]]</li>
<li>[[expecco ALM Einrichten Vorgehensweise|expecco ALM Einrichten]]</li>
<li>[[expecco ALM expecco Patch Service |Patchservice für expecco]]</li>
</ul>
</div>

<div style="background-color:#ecf0fe; margin:12px 8px 0 0; flex:1 0 auto">

[[Datei:Refresh.png|30px]]Plugins<hr>

<ul style="font-size:0.8em; padding:0.7em 1em 1em 2.4em">
<li>[[AIDYMO Jira|Atlassian Jira]]</li>
<li>[[CustomerSpecific|Kundenspezifische Portale]]</li>
</ul>
</div>

<div style="background-color:#ecf0fe; margin:12px 8px 0 0; flex:1 0 auto">

[[Datei:Refresh.png|30px]]Sonstiges<hr>

<ul style="font-size:0.8em; padding:0.7em 1em 1em 2.4em">
<li>[[expecco ALM App]]</li>
<li>[[Installation Lizenzserver]]</li>
<li>[[expecco ALM Release Notes|Release Notes]]</li>
<li>[[expecco ALM Known Issues|Known Issues]]</li>
</ul>
</div>
</div>

Release Notes 25.x

2025-06-23T10:17:26Z

Sv:

See also: [[Release Notes 24.x]]
 

== Release 25.1 (Scheduled for June 2025) ==
*Improvement: additional "Info" tab in inspector views
*Improvement: less memory usage in the activity log
*Improvement: better error messages and more links to settings from the activity log's error message
*Improvement: additional units and conversions in the [[PhysicalValues/en|physical values framework]]
*Improvement: more precision in the [[Numeric_Limits/en#Higher_Precision_Numbers|high precision trigonometric and math functions]]
*Improvement: WindowsAutomation: Plugn Update to FlaUI 5
*Improvement: Mobile Testing: Better Device Lock/Unlock Support
*Improvement: StandardLibrary: "File [ *CSV ]" blocks got an additional "characterEncodeing" pin (useful for reading/writing e.g. utf-8 encoded CSV files)
*Improvement: ExcelLib: better documentation. Now requires the openpyxl package version >= 3.1.5.
*Improvement: better model language editor (translate and fetch-strings functions)
*Improvement: ODBClibrary: improved compatibility with different database vendors (supports the CedarDB database)
*Feature: translate and spell check in the workspace window
*Feature: EditLock of suites loaded from expeccoALM / AIDYMO
*Feature: Start Test in expeccoALM / AIDYMO (via expecco)
*Feature: new library containing expeccoALM control actions (those from the AIDYMO menu)
*Fix: the version diff viewer (did not correctly copy changed attachment files)

Release Notes 25.x

2025-06-23T10:03:40Z

Sv: /* Release 25.1 (Scheduled for May 2025) */

See also: [[Release Notes 24.x]]
 

== Release 25.1 (Scheduled for May 2025) ==
*Improvement: additional "Info" tab in inspector views
*Improvement: less memory usage in the activity log
*Improvement: better error messages and more links to settings from the activity log's error message
*Improvement: additional units and conversions in the [[PhysicalValues/en|physical values framework]]
*Improvement: more precision in the [[Numeric_Limits/en#Higher_Precision_Numbers|high precision trigonometric and math functions]]
*Improvement: WindowsAutomation: Plugn Update to FlaUI 5
*Improvement: Mobile Testing: Better Device Lock/Unlock Support
*Improvement: StandardLibrary
*Improvement: better model language editor (translate and fetch-strings functions)

*Feature: translate and spell check in the workspace window
*Feature: EditLock of suites loaded from expeccoALM / AIDYMO
*Feature: Start Test in expeccoALM / AIDYMO (via expecco)
*Feature: new library containing expeccoALM control actions (those from the AIDYMO menu)
*Fix: the version diff viewer (did not correctly copy changed attachment files)