Table of Contents

Class ExpressionSink

Namespace
Bonsai.Scripting.Expressions
Assembly
Bonsai.Scripting.Expressions.dll

Represents an operator that uses an expression script to invoke an action for each element of an observable sequence.

Warning

In general the use of this operator should be avoided. Its main purpose is to trigger or evaluate side-effects in elements of the input sequence, which can break the immutability of values and create confusion. However, in specific applications it might be one of the few ways to interface with a specific API.

Expression Language

The Scripting.Expressions namespace uses an early version of the Dynamic LINQ library to assemble expression trees directly into the workflow by using a special syntax.

Note

This expression language aims to be a simple and convenient way of writing arithmetical and value manipulation operations without having to create a separate project or manage local extensions, but it is not a complete query or programming language. If you require more elaborate type or value manipulations, please consider writing a custom scripting extension.

Literals

The expression language supports boolean, integer, real, string, and character literals. Literals are textual representations of constant values and are one of the most important building blocks of an expression.

Type Examples Description
boolean true
false		 A Boolean value which can be either true or false.
integer 0
1L
2U
3UL		 A sequence of digits. The type of an integer literal is Int32 unless a qualifier character is used to specify the type of the integer (U - UInt32, L - Int64, UL - UInt64).
real 1.0
2.25
1e10F
1.2345E-4		 An integral part followed by a fractional part and/or an exponent. The fractional part is a decimal point followed by one or more digits. The exponent is the letter e or E followed by an optional + or - sign followed by one or more digits. The type of a real literal is Double unless the F qualifier is used, in which case the type of the literal will be Single.
string "hello"
""
"""quoted"""
"'"		 Zero or more characters enclosed in double quotes. A double quote character can be represented inside a string literal using two consecutive double quotes. The type of a string literal is String.
character 'A'
'1'
''''
'"'		 A single character enclosed in single quotes. A single quote character can be represented inside a character literal using two consecutive single quotes. The type of a character literal is Char.
null null The null literal represents a null reference. The type of the null literal is Object.

Types

The expression language defines special keywords representing the primitive types and a small set of accessible types from the System namespace of the .NET Framework Base Class Library.

These accessible types can be used to create new values, convert a value to another type, or to call public static methods available from the type class, as detailed in the documentation reference page of each type.

Type
 Description
Boolean Represents a Boolean (true or false) value.
Byte Represents an 8-bit unsigned integer.
Char Represents a character as a UTF-16 code unit.
DateTime Represents an instant in time, typically expressed as a date and time of day.
DateTimeOffset Represents a point in time, typically expressed as a date and time of day, relative to Coordinated Universal Time (UTC).
Decimal Represents a decimal floating-point number.
Double Represents a double-precision floating-point number.
Guid Represents a globally unique identifier (GUID).
Int16 Represents a 16-bit signed integer.
Int32 Represents a 32-bit signed integer.
Int64 Represents a 64-bit signed integer.
Object Supports all classes in the .NET class hierarchy and provides low-level services to derived classes. This is the ultimate base class of all .NET classes; it is the root of the type hierarchy.
SByte Represents an 8-bit signed integer.
Single Represents a single-precision floating-point number.
String Represents text as a sequence of UTF-16 code units.
TimeSpan Represents a time interval.
UInt16 Represents a 16-bit unsigned integer.
UInt32 Represents a 32-bit unsigned integer.
UInt64 Represents a 64-bit unsigned integer.
Math Provides constants and static methods for trigonometric, logarithmic, and other common mathematical functions.
Convert Converts a base data type to another base data type.
Note

Nullable value types can be specified by writing a ? after the type name. For example, Int32? refers to the nullable form of Int32.

Conversions

The expression language allows explicit conversions between value types using the syntax type(_expr_) where type is one of the primitive types listed above, optionally followed by ?, and _expr_ is an arbitrary expression, e.g. the expression Int32(22.5) will convert the real number 22.5 to an integer with the type Int32.

Note

This syntax can be used to convert between the nullable and non-nullable forms of any value type.

Identifiers

When parsing an expression with a single input element, all members in that element are automatically in scope of the expression string, including public fields, public properties, and public methods. This means any specific member on the input can be accessed by writing an identifier corresponding to the name of that member, e.g. Item1.

Warning

The casing of identifiers is ignored when resolving members, e.g. item1 or ITEM1 can both be used to refer to the member Item1.

An identifier consists of a letter or underscore followed by any number of letters, digits, or underscores. In order to reference an identifier with the same spelling as a keyword, the identifier must be prefixed with a single @ character. Some examples of identifiers are x, Hello, m_1, @true and @String.

Note

The special keyword it represents the entire input element, and members can be accessed from this special identifier using dot notation, e.g. it.Item1.

Operators

The expression language supports the following operators in order of precedence of the categories indicated in the table, from top to bottom. Operators in the same category have equal precedence.

In the table below, x, y, and z refer to arbitrary expressions, T refers to one of the accessible types, and m refers to a member of an expression value (see the section on identifiers).

Category
Expression
 Description
Primary x.m Instance field or property access. Any public field or property can be accessed.
Primary x.m(...) Instance method invocation. Any public method may be invoked. Overload resolution follows C# rules.
Primary x[...] Array or indexer access. Any public indexer, including multi-dimensional indexers, can be accessed.
Primary T.m Static field or static property access. Any public field or property can be accessed.
Primary T.m(...) Static method invocation. Any public method may be invoked. Overload resolution follows C# rules.
Primary T(...) Explicit conversion or constructor invocation.
Primary new(...) Data object initializer. This syntax can be used to perform dynamic projections.
Primary it Current instance access. See the note in the section on identifiers.
Primary iif(x, y, z) Conditional expression. Alternate syntax for x ? y : z.
Unary -x Negation using two's complement. Supported types are Int32, UInt32, Int64, Decimal, Single, and Double.
Unary !x Logical negation. Operand must be of type Boolean.
Multiplicative x * y Multiplication. Only primitive numeric types are supported.
Multiplicative x / y Division. Only primitive numeric types are supported.
Multiplicative x % y Remainder. Only primitive numeric types are supported.
Additive x + y Addition or string concatenation. Performs string concatenation if either operand is of type String. Otherwise, performs addition on primitive numeric types only.
Additive x - y Subtraction. Only primitive numeric types are supported.
Additive x & y String concatenation. Operands must both be of type String.
Relational x == y Equal. Supported for reference types and any of the primitive types. Comparison with null is also supported.
Relational x != y Not equal. Supported for reference types and any of the primitive types. Comparison with null is also supported.
Relational x < y Less than. Supported for all primitive types except Boolean, Object and Guid.
Relational x > y Greater than. Supported for all primitive types except Boolean, Object and Guid.
Relational x <= y Less than or equal. Supported for all primitive types except Boolean, Object and Guid.
Relational x >= y Greater than or equal. Supported for all primitive types except Boolean, Object and Guid.
Logical AND x && y Logical AND. Operands must be of type Boolean.
Logical OR x || y Logical OR. Operands must be of type Boolean.
Conditional x ? y : z Evaluate y if x is true, otherwise evaluate z.

Data Object Initializers

The expression language supports creating dynamic data classes using data object initializers. A data object initializer simultaneously specifies a data class and creates a new instance of that class. The specific properties of the data class are inferred from the data object initializer.

The syntax for a data object initializer is identical to a constructor, where each argument represents a property of the data class. For each argument the value must be specified together with an identifier for the property name, separated by the as keyword:

new(
  Item1 as X,
  Item2 as Y
)

The example above projects the two unnamed items of a tuple into a new data object with an X and a Y property.

Examples

The following examples demonstrate some actions achievable with this operator.

Category Example Description
Method Invocation it.Update() Invoke the method Update on all the elements of the input sequence.
Property Assignment set_Delay(1) Assign a value to the Delay property. The expression language does not directly support assignment, but we can refer to the setter method by its canonical identifier set_P where P is the name of the property.
Warning

Property assignment is only supported on reference types since for value types the expression will be evaluated on a copy of the value. This new value will not be included in the output sequence since a Sink operator does not modify the elements of the original sequence.

[WorkflowElementCategory(ElementCategory.Sink)]
public class ExpressionSink : SingleArgumentExpressionBuilder, IExpressionBuilder, INamedElement
Inheritance
ExpressionSink
Implements
Inherited Members
Extension Methods

Properties

Description

Gets or sets a description for the expression sink.

Expression

Gets or sets the expression that determines the action to perform on the input elements.

Name

Gets or sets the name of the expression sink.

Methods

Build(IEnumerable<Expression>)

Constructs an Expression node from a collection of input arguments. The result can be chained with other builders in a workflow.

Edit this page