Class ExpressionTransform

Namespace

Bonsai.Scripting.Expressions

Assembly

Bonsai.Scripting.Expressions.dll

Represents an operator that uses an expression script to transform each element of an observable sequence.

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 common Transforms achievable with this operator.

Category	Example	Description
Arithmetic Operations	1.0 / (it + 2.0)	Transform an element using arithmetic operators.
Arithmetic Operations	Math.Sqrt(it)	Transform an element using functions provided by the Math class.
Attribute Renaming	new(Item1 as X, Item2 as Y)	Project the members of an element into a new data object. Commonly used to rename object attributes.
Conditional Expression	it ? 1 : 0	Convert a Boolean value into an integer or numerical type.
Type Conversion	Double(it)	Explicitly convert a primitive numeric type to a Double.
Type Conversion	Convert.ToDouble(it)	Convert an element of any primitive type (including String values) to a Double using the Convert class.
Type Conversion	TimeSpan.FromSeconds(it)	Convert a primitive value type into another type by directly invoking a static method in the target type.

[WorkflowElementCategory(ElementCategory.Transform)]
public class ExpressionTransform : SingleArgumentExpressionBuilder, IExpressionBuilder, INamedElement

Inheritance

object

ExpressionBuilder

SingleArgumentExpressionBuilder

ExpressionTransform

Implements

IExpressionBuilder

INamedElement

Inherited Members

SingleArgumentExpressionBuilder.ArgumentRange

ExpressionBuilder.ToString()

ExpressionBuilder.Unwrap(ExpressionBuilder)

ExpressionBuilder.GetWorkflowElement(ExpressionBuilder)

ExpressionBuilder.GetVisualizerElement(ExpressionBuilder)

ExpressionBuilder.GetVisualizerMappings(ExpressionBuilder)

ExpressionBuilder.FromWorkflowElement(object, ElementCategory)

ExpressionBuilder.GetElementDisplayName(Type)

ExpressionBuilder.GetElementDisplayName(object)

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

Extension Methods

ExpressionBuilderGraphExtensions.AsInspectBuilder(ExpressionBuilder)

ExpressionBuilderGraphExtensions.Build(ExpressionBuilder, params Expression[])

ExpressionBuilderGraphExtensions.IsBuildDependency(ExpressionBuilder)

Properties

Description

Gets or sets a description for the expression transform.

Expression

Gets or sets the expression that determines the operation of the transform.

Name

Gets or sets the name of the expression transform.

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.