DiagramElements-FreezeValue/en

Aus expecco Wiki (Version 2.x)
Zur Navigation springen Zur Suche springen

Introduction[Bearbeiten]

A so called "Freeze Value" is a constant value attached to an input pin. When executed, that value will be presented to the action.

Be aware, that frozen pin values should normally not be consumed; i.e. in case the step is executed twice, the value should still be present for the second incarnation. This is especially important if a step is executed in a loop or triggered by a step which writes multiple values to an output.

Thus, the diagram editor will automatically change the pin's behavior to non-triggering and non-consuming (i.e. make it a "parameter pin").

The following describes the data format and syntax used in pin freeze values. In general, the text entered as freeze value is parsed by the input pin's datatype.

Format for Particular Types[Bearbeiten]

Integer[Bearbeiten]

Integer constants can be entered in one of the following formats:

  • decimal (for example: "1234" , "-1234)
  • with Smalltalk radix prefix: (for example: "16rCAFE" , "16r-AA, "8r100, "2r101010000) any radix between 2 and 36 is allowed.
  • with C radix prefix: (for example: "0xCAFE" , "-0xAA, "0b101010000) ("0x" for hex, "0o" for octal and "0b" for binary).
    Notice that the C-octal notation (prefix 0) is not supported (ie. "0377" will be read as 377).

Float[Bearbeiten]

By default, floats are represented as double-precision IEEE limited precision rationals (64 bit). You can force single precision floats by using the 'f' exponent indicator.

  • double precision floats such as: "123.0", "+123.0", "-123.0", ".123", "123.", "123.0e+2", "123.0e-2"
  • single precision: "123.0f+2" or "-123.0f"
  • extended precision: "123.0q+2" or "-123.0q"

Do not expect any speed or other advantages when using single precision floats. Actually, expect problems due to larger errors, non-stable series computations etc. Use them only if you need to emulate less precise computations.

Extended precision floats may not be supported by all CPU types (these use the underlying machine's "long double" data type, which is either an 80-bit extended IEEE or a 128-bit quadruple IEEE float. As not all CPUs do support these, we cannot guarantee that future machines will support them. However, currently all supported machine architectures do.

String[Bearbeiten]

If the pin's datatype is String, then no leading/trailing quotes are needed (actually: if there are quotes, these will be part of the string).
However, quotes are needed if the type is not unambiguously a String type (i.e. Any or a Union type).

By default, NO C-style escape sequences are interpreted - i.e. the string is taken "as-is".
If you want or need those, either enable the "C-Escapes" toggle via the freeze-value's popup menu, or freeze it as "C-String", which is a pseudo datatype offered in the freeze as menu.

You can then use the escapes:

  • "\n" for a newline character
  • "\r" for a return character
  • "\t" for a tab
  • "\b" for a backspace
  • "\xXX" for a single byte hex-character code
  • "\uXXXX" for a 32bit hex-character code
  • "\\" for the "\" character.
  • "\0" for a null character (null byte)

By default, variables of the form "$(xxx)" are expanded from either an expecco variable or the shell environment. Thus,

  • "$(HOME)/foo/bar" will expand to the name of a subdirectory "foo/bar" under your home directory (in unix). Or if you have a variable named "HOME" in the expecco environment, to whatever that value is.

This behavior can be disabled via the freeze value's popup menu.

In addition, variables of the form "%(xxx)" are expanded by the value of the input pin named "xxx". This expansion is also controlled by a flag in the popup menu.

Freeze value expansion can be suppressed either in the basket itself (the freeze-menu), or globally via a flag in the project, to enforce backward compatibility of a whole library (in the rare situation, that an older library depends on such freeze values being unchanged).

Be reminded, that these variable expansions are only done for freeze values. If the value comes from another pin, it is passed unchanged.

Bytes (ByteArray)[Bearbeiten]

Byte data can be entered in multiple forms:

  • Smalltalk format: "#[ 1 2 3 ]" (spaces between byte values)
  • JSON format: "[ 1, 2, 3 ]" (commas between byte values)
  • C format: "{ 1, 2, 3 }" (braces and commas between byte values)
  • hex format: "xxXXxxXX" (two hex characters per byte; no spaces in-between)
  • hex format: "xx XX xx XX" (two hex characters per byte; with spaces in-between)

Geometric Objects (Points and Rectangles)[Bearbeiten]

Points are entered (in Smalltalk syntax) as:

  • <x> @ <y>
  • Point x:<x> y:<y>

where <x> and <y> are numeric constants (typically integers).

Rectangles (in Smalltalk syntax):

  • (<xL> @ <yT>) extent:(<w> @ <h>)
  • (<xL> @ <yT>) corner:(<xR> @ <yB>)
  • Rectangle left:<xL> top:<yT> width:<wT> height:<hT>
  • Rectangle left:<xL> top:<yT> right:<xR> bottom:<yB>

where <xL> and <yT> is the left and top coordinates, <xR> and <yB> are the coordinates of the corner (the first pixel outside the rectangle), and <w> and <h> are the extent (width and height) of the rectangle.

Any[Bearbeiten]

To distinguish between strings and non-strings, String-constants for an Any-typed pin or a type which accepts both strings and non-strings (i.e. unions), a string value must be quoted.
For example:

  • 1234 - will be an integer value
  • 1234.56 - will be a float value
  • '1234' - will be a string value

Variable Expansion[Bearbeiten]

Inside a freeze value, variable values can be embedded using the "$(...)" notation, unless the freeze value has the "No Variable Expansion flag set via the freeze value's popup menu).

$(...) Expansion[Bearbeiten]

In addition to the visible environment variables, the following builtin names are allowed:

  • AttachmentsDirectory - the directory, where all attachments of the suite are located.
  • Attachments - the same, but a little shorter
  • ExecutionDirectory - a temporary directory, which vanishes after the execution
  • ExpeccoInstallationDirectory - the directory, where expecco was installed
  • ExpeccoLibraryDirectory - the directory, where the libraries delivered with expecco live (first supported in 23.1)
  • ExpeccoPluginDirectory - the directory, where expecco's plugins are installed
  • ProjectDirectory - the temporary project directory
  • HomeDirectory - the user's home directory
  • TmpDirectory - a temporary directory (subfolder of the system's tmp directory)
  • CurrentDirectory - the "current" directory (see below)
  • DocumentsDirectory - the "documents" directory
  • DesktopDirectory - the "desktop" directory
  • LoginName - your login name (username under Unix/Linux/OSX)
  • UserName - your full name (if known, otherwise the login name)
  • <inPinName> - where inPinName is the name of an input pin of the containing compound action

If the script must run somewhere else, you can provide the path at the block's "execDir" input pin (or for shell scripts, you can also specify it in the editor, which is effectively defining the directory as a freeze value). The execution directory pathname (provided at the pin) may contain placeholders in the form "$(xxx)", where "xxx" is either a shell environment variable, or one of the above listed builtin placeholder variables.

Popup Menu[Bearbeiten]

Of special interest are the entries:

JSON Encoded[Bearbeiten]

The freeze value's text is a JSON string, and the decoded object is passed to the action as pin-value. Be careful to provide correct syntax here.


Array:

[  <element1> , <element2> , ... <elementN> ]

Object:

{ "<fieldName1>": <fieldValue1> , 
  "<fieldName2>": <fieldValue2> ,
             ...
  "<fieldNameN>": <fieldValueN>
}

Other:

  true
  false
  null
  <integer>
  <float>

A future version may provide additional syntax checks in this editor. For now, we assume that most of us will simply copy-paste a JSON string from some other place. Let us know, if that would be a high priority feature in the next version.

C-Style Escapes[Bearbeiten]

The freeze value's text is a string with C-style escape sequences (see above).

No Variable Expansion[Bearbeiten]

No variables are expanded inside the freeze value. Use this, to pass strings eg. to shell scripts, which require strings with embedded $(...) sequences.



Copyright © 2014-2024 eXept Software AG