Add a ternary operator 'replace' (#521)

* feat: ✨ Added a replace ternary operator

Author: rhazn

apps/docs/docs/dev/04-guides/04-expressions-and-operators.md

@@ -11,8 +11,8 @@ As a small practical example, you may also have a look at the [arithmetics examp
 
 ## Expressions in the grammar
 
-Expressions in the Jayvee grammar are defined in [`expression.langium`](https://github.com/jvalue/jayvee/blob/main/libs/language-server/src/grammar/expression.langium) and consist of operators (unary / binary) and literals.
-Unary operators only have a single operand (e.g. the `not` operator) whereas binary operators require two operands (e.g. the `*` operator).
+Expressions in the Jayvee grammar are defined in [`expression.langium`](https://github.com/jvalue/jayvee/blob/main/libs/language-server/src/grammar/expression.langium) and consist of operators (unary / binary / ternary) and literals.
+Unary operators only have a single operand (e.g. the `not` operator), binary operators require two operands (e.g. the `*` operator) and ternary operators require three operands.
 
 The grammar is written in a way that literals end up in the leaves of the resulting AST and the nodes above represent the operators.
 

apps/docs/docs/user/expressions.md

@@ -15,10 +15,10 @@ Expressions get evaluated at runtime by the interpreter to a [Built-in ValueType
 
 The following expression is evaluated to the `integer` `10`: `(2 + 3) * 2`
 
-The following expression is evaluated to the `integer` `3`: `floor (3.14)`
-
 The following expression is evaluated to the `boolean` `true`: `"Example" == "Example"`
 
+The following expression is evaluated to the `text` `I love Datypus`: `"I love platypuses" replace /platypuses/ with "Datypus"`
+
 ### List of Operators
 
 #### Arithmetics (binary operators)
@@ -58,6 +58,9 @@ The following expression is evaluated to the `boolean` `true`: `"Example" == "Ex
 - `matches` for a regex match, e.g., `"A07" matches /^[A-Z0-9]*$/` evaluates to `true`
 - `in` for inclusion in an array, e.g., `"a" in ["a", "b", "c"]` evaluates to `true`
 
+#### Text manipulation (ternary operators)
+- `replace [...] with [...]` replaces regex matches in a text with a string
+
 ### Operator Details
 
 #### `in` Operator

libs/language-server/src/grammar/expression.langium

@@ -10,10 +10,13 @@ import './terminal'
 import './transform'
 
 Expression:
-  OrExpression;
+  ReplaceExpression;
 
 // The nesting of the following rules implies the precedence of the operators:
 
+ReplaceExpression infers Expression:
+  OrExpression ({infer TernaryExpression.first=current} operator='replace' second=OrExpression 'with' third=OrExpression)*;
+
 OrExpression infers Expression:
   AndExpression ({infer BinaryExpression.left=current} operator='or' right=AndExpression)*;
 

libs/language-server/src/lib/ast/expressions/evaluation.ts

@@ -26,6 +26,7 @@ import {
   isReferenceLiteral,
   isRegexLiteral,
   isRuntimeParameterLiteral,
+  isTernaryExpression,
   isTransformDefinition,
   isTransformPortDefinition,
   isUnaryExpression,
@@ -41,6 +42,7 @@ import { type InternalValueRepresentation } from './internal-value-representatio
 // eslint-disable-next-line import/no-cycle
 import {
   binaryOperatorRegistry,
+  ternaryOperatorRegistry,
   unaryOperatorRegistry,
 } from './operator-registry';
 import { isEveryValueDefined } from './typeguards';
@@ -223,6 +225,11 @@ export function evaluateExpression(
     const evaluator = binaryOperatorRegistry[operator].evaluation;
     return evaluator.evaluate(expression, evaluationContext, strategy, context);
   }
+  if (isTernaryExpression(expression)) {
+    const operator = expression.operator;
+    const evaluator = ternaryOperatorRegistry[operator].evaluation;
+    return evaluator.evaluate(expression, evaluationContext, strategy, context);
+  }
   assertUnreachable(expression);
 }
 

libs/language-server/src/lib/ast/expressions/evaluators/replace-operator-evaluator.ts

@@ -0,0 +1,25 @@
+// SPDX-FileCopyrightText: 2023 Friedrich-Alexander-Universitat Erlangen-Nurnberg
+//
+// SPDX-License-Identifier: AGPL-3.0-only
+
+// eslint-disable-next-line import/no-cycle
+import { DefaultTernaryOperatorEvaluator } from '../operator-evaluator';
+import { REGEXP_TYPEGUARD, STRING_TYPEGUARD } from '../typeguards';
+
+export class ReplaceOperatorEvaluator extends DefaultTernaryOperatorEvaluator<
+  string,
+  RegExp,
+  string,
+  string
+> {
+  constructor() {
+    super('replace', STRING_TYPEGUARD, REGEXP_TYPEGUARD, STRING_TYPEGUARD);
+  }
+  override doEvaluate(
+    firstValue: string,
+    secondValue: RegExp,
+    thirdValue: string,
+  ): string {
+    return firstValue.replace(secondValue, thirdValue);
+  }
+}

libs/language-server/src/lib/ast/expressions/operator-evaluator.ts

@@ -5,10 +5,15 @@
 import { strict as assert } from 'assert';
 
 import { ValidationContext } from '../../validation/validation-context';
-import { BinaryExpression, UnaryExpression } from '../generated/ast';
+import {
+  BinaryExpression,
+  TernaryExpression,
+  UnaryExpression,
+} from '../generated/ast';
 // eslint-disable-next-line import/no-cycle
 import {
   BinaryExpressionOperator,
+  TernaryExpressionOperator,
   UnaryExpressionOperator,
 } from '../model-util';
 
@@ -23,7 +28,7 @@ import {
 } from './internal-value-representation';
 
 export interface OperatorEvaluator<
-  E extends UnaryExpression | BinaryExpression,
+  E extends UnaryExpression | BinaryExpression | TernaryExpression,
 > {
   readonly operator: E['operator'];
 
@@ -189,3 +194,82 @@ export abstract class BooleanShortCircuitOperatorEvaluator
     return this.doEvaluate(leftValue, rightValue);
   }
 }
+
+export abstract class DefaultTernaryOperatorEvaluator<
+  FirstValue extends InternalValueRepresentation,
+  SecondValue extends InternalValueRepresentation,
+  ThirdValue extends InternalValueRepresentation,
+  ReturnValue extends InternalValueRepresentation,
+> implements OperatorEvaluator<TernaryExpression>
+{
+  constructor(
+    public readonly operator: TernaryExpressionOperator,
+    private readonly firstValueTypeguard: InternalValueRepresentationTypeguard<FirstValue>,
+    private readonly secondValueTypeguard: InternalValueRepresentationTypeguard<SecondValue>,
+    private readonly thirdValueTypeguard: InternalValueRepresentationTypeguard<ThirdValue>,
+  ) {}
+
+  protected abstract doEvaluate(
+    firstValue: FirstValue,
+    secondValue: SecondValue,
+    thirdValue: ThirdValue,
+    expression: TernaryExpression,
+    context: ValidationContext | undefined,
+  ): ReturnValue | undefined;
+
+  evaluate(
+    expression: TernaryExpression,
+    evaluationContext: EvaluationContext,
+    strategy: EvaluationStrategy,
+    validationContext: ValidationContext | undefined,
+  ): ReturnValue | undefined {
+    // The following linting exception can be removed when a second ternary operator is added
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    assert(expression.operator === this.operator);
+
+    const firstValue = evaluateExpression(
+      expression.first,
+      evaluationContext,
+      validationContext,
+      strategy,
+    );
+
+    if (strategy === EvaluationStrategy.LAZY && firstValue === undefined) {
+      return undefined;
+    }
+
+    const secondValue = evaluateExpression(
+      expression.second,
+      evaluationContext,
+      validationContext,
+      strategy,
+    );
+
+    const thirdValue = evaluateExpression(
+      expression.third,
+      evaluationContext,
+      validationContext,
+      strategy,
+    );
+
+    if (
+      firstValue === undefined ||
+      secondValue === undefined ||
+      thirdValue === undefined
+    ) {
+      return undefined;
+    }
+
+    assert(this.firstValueTypeguard(firstValue));
+    assert(this.secondValueTypeguard(secondValue));
+    assert(this.thirdValueTypeguard(thirdValue));
+
+    return this.doEvaluate(
+      firstValue,
+      secondValue,
+      thirdValue,
+      expression,
+      validationContext,
+    );
+  }
+}

libs/language-server/src/lib/ast/expressions/operator-registry.ts

@@ -4,9 +4,14 @@
 
 /* eslint-disable import/no-cycle */
 
-import { BinaryExpression, UnaryExpression } from '../generated/ast';
+import {
+  BinaryExpression,
+  TernaryExpression,
+  UnaryExpression,
+} from '../generated/ast';
 import {
   BinaryExpressionOperator,
+  TernaryExpressionOperator,
   UnaryExpressionOperator,
 } from '../model-util';
 
@@ -30,6 +35,7 @@ import { NotOperatorEvaluator } from './evaluators/not-operator-evaluator';
 import { OrOperatorEvaluator } from './evaluators/or-operator-evaluator';
 import { PlusOperatorEvaluator } from './evaluators/plus-operator-evaluator';
 import { PowOperatorEvaluator } from './evaluators/pow-operator-evaluator';
+import { ReplaceOperatorEvaluator } from './evaluators/replace-operator-evaluator';
 import { RootOperatorEvaluator } from './evaluators/root-operator-evaluator';
 import { RoundOperatorEvaluator } from './evaluators/round-operator-evaluator';
 import { SqrtOperatorEvaluator } from './evaluators/sqrt-operator-evaluator';
@@ -38,6 +44,7 @@ import { XorOperatorEvaluator } from './evaluators/xor-operator-evaluator';
 import { OperatorEvaluator } from './operator-evaluator';
 import {
   BinaryOperatorTypeComputer,
+  TernaryOperatorTypeComputer,
   UnaryOperatorTypeComputer,
 } from './operator-type-computer';
 import { BasicArithmeticOperatorTypeComputer } from './type-computers/basic-arithmetic-operator-type-computer';
@@ -50,6 +57,7 @@ import { LogicalOperatorTypeComputer } from './type-computers/logical-operator-t
 import { MatchesOperatorTypeComputer } from './type-computers/matches-operator-type-computer';
 import { NotOperatorTypeComputer } from './type-computers/not-operator-type-computer';
 import { RelationalOperatorTypeComputer } from './type-computers/relational-operator-type-computer';
+import { ReplaceOperatorTypeComputer } from './type-computers/replace-operator-type-computer';
 import { SignOperatorTypeComputer } from './type-computers/sign-operator-type-computer';
 import { SqrtOperatorTypeComputer } from './type-computers/sqrt-operator-type-computer';
 
@@ -174,3 +182,18 @@ export const binaryOperatorRegistry: Record<
     evaluation: new OrOperatorEvaluator(),
   },
 };
+
+export interface TernaryOperatorEntry {
+  typeInference: TernaryOperatorTypeComputer;
+  evaluation: OperatorEvaluator<TernaryExpression>;
+}
+
+export const ternaryOperatorRegistry: Record<
+  TernaryExpressionOperator,
+  TernaryOperatorEntry
+> = {
+  replace: {
+    typeInference: new ReplaceOperatorTypeComputer(),
+    evaluation: new ReplaceOperatorEvaluator(),
+  },
+};

libs/language-server/src/lib/ast/expressions/operator-type-computer.ts

@@ -3,7 +3,11 @@
 // SPDX-License-Identifier: AGPL-3.0-only
 
 import { ValidationContext } from '../../validation/validation-context';
-import { BinaryExpression, UnaryExpression } from '../generated/ast';
+import {
+  BinaryExpression,
+  TernaryExpression,
+  UnaryExpression,
+} from '../generated/ast';
 import { type Valuetype } from '../wrappers/value-type/valuetype';
 
 export interface UnaryOperatorTypeComputer {
@@ -127,3 +131,100 @@ export function generateUnexpectedTypeMessage(
 ) {
   return `The operand needs to be of type ${expectedType.getName()} but is of type ${actualType.getName()}`;
 }
+
+export abstract class DefaultTernaryOperatorTypeComputer
+  implements TernaryOperatorTypeComputer
+{
+  constructor(
+    protected readonly expectedFirstOperandType: Valuetype,
+    protected readonly expectedSecondOperandType: Valuetype,
+    protected readonly expectedThirdOperandType: Valuetype,
+  ) {}
+
+  computeType(
+    firstOperandType: Valuetype,
+    secondOperandType: Valuetype,
+    thirdOperandType: Valuetype,
+    expression: TernaryExpression,
+    context: ValidationContext | undefined,
+  ): Valuetype | undefined {
+    let typeErrorOccurred = false;
+
+    if (!firstOperandType.isConvertibleTo(this.expectedFirstOperandType)) {
+      context?.accept(
+        'error',
+        generateUnexpectedTypeMessage(
+          this.expectedFirstOperandType,
+          firstOperandType,
+        ),
+        {
+          node: expression.first,
+        },
+      );
+      typeErrorOccurred = true;
+    }
+
+    if (!secondOperandType.isConvertibleTo(this.expectedSecondOperandType)) {
+      context?.accept(
+        'error',
+        generateUnexpectedTypeMessage(
+          this.expectedSecondOperandType,
+          secondOperandType,
+        ),
+        {
+          node: expression.second,
+        },
+      );
+      typeErrorOccurred = true;
+    }
+
+    if (!thirdOperandType.isConvertibleTo(this.expectedThirdOperandType)) {
+      context?.accept(
+        'error',
+        generateUnexpectedTypeMessage(
+          this.expectedThirdOperandType,
+          thirdOperandType,
+        ),
+        {
+          node: expression.third,
+        },
+      );
+      typeErrorOccurred = true;
+    }
+
+    if (typeErrorOccurred) {
+      return undefined;
+    }
+
+    return this.doComputeType(
+      firstOperandType,
+      secondOperandType,
+      thirdOperandType,
+    );
+  }
+
+  protected abstract doComputeType(
+    firstOperandType: Valuetype,
+    secondOperandType: Valuetype,
+    thirdOperandType: Valuetype,
+  ): Valuetype;
+}
+
+export interface TernaryOperatorTypeComputer {
+  /**
+   * Computes the type of a ternary operator by the type of its operands.
+   * @param firstType the type of the first operand
+   * @param secondType the type of the second operand
+   * @param thirdType the type of the third operand
+   * @param expression the expression to use for diagnostics
+   * @param context the validation context to use for diagnostics
+   * @returns the resulting type of the operator or `undefined` if the type could not be inferred
+   */
+  computeType(
+    firstType: Valuetype,
+    secondType: Valuetype,
+    thirdType: Valuetype,
+    expression: TernaryExpression,
+    context: ValidationContext | undefined,
+  ): Valuetype | undefined;
+}