github.com/expr-lang/expr@v1.16.9/docs/configuration.md (about)

     1  # Configuration
     2  
     3  ## Return type
     4  
     5  Usually, the return type of expression is anything. But we can instruct type checker to verify the return type of the
     6  expression.
     7  For example, in filter expressions, we expect the return type to be a boolean.
     8  
     9  ```go 
    10  program, err := expr.Compile(code, expr.AsBool())
    11  if err != nil {
    12  panic(err)
    13  }
    14  
    15  output, err := expr.Run(program, env)
    16  if err != nil {
    17  panic(err)
    18  }
    19  
    20  ok := output.(bool) // It is safe to assert the output to bool, if the expression is type checked as bool.
    21  ```
    22  
    23  If `code` variable for example returns a string, the compiler will return an error.
    24  
    25  Expr has a few options to specify the return type:
    26  
    27  - [expr.AsBool()](https://pkg.go.dev/github.com/expr-lang/expr#AsBool) - expects the return type to be a bool.
    28  - [expr.AsInt()](https://pkg.go.dev/github.com/expr-lang/expr#AsInt) - expects the return type to be an int (float64,
    29    uint, int32, and other will be cast to int).
    30  - [expr.AsInt64()](https://pkg.go.dev/github.com/expr-lang/expr#AsInt64) - expects the return type to be an int64 (
    31    float64, uint, int32, and other will be cast to int64).
    32  - [expr.AsFloat64()](https://pkg.go.dev/github.com/expr-lang/expr#AsFloat64) - expects the return type to be a float64 (
    33    float32 will be cast to float64).
    34  - [expr.AsAny()](https://pkg.go.dev/github.com/expr-lang/expr#AsAny) - expects the return type to be anything.
    35  - [expr.AsKind(reflect.Kind)](https://pkg.go.dev/github.com/expr-lang/expr#AsKind) - expects the return type to be a
    36    specific kind.
    37  
    38  :::tip Warn on any
    39  By default, type checker will accept any type, even if the return type is specified. Consider following examples:
    40  
    41  ```expr
    42  let arr = [1, 2, 3]; arr[0]
    43  ```
    44  
    45  The return type of the expression is `any`. Arrays created in Expr are of type `[]any`. The type checker will not return
    46  an error if the return type is specified as `expr.AsInt()`. The output of the expression is `1`, which is an int, but the
    47  type checker will not return an error.
    48  
    49  But we can instruct the type checker to warn us if the return type is `any`. Use [`expr.WarnOnAny()`](https://pkg.go.dev/github.com/expr-lang/expr#WarnOnAny) to enable this behavior.
    50  
    51  ```go
    52  program, err := expr.Compile(code, expr.AsInt(), expr.WarnOnAny())
    53  ```
    54  
    55  The type checker will return an error if the return type is `any`. We need to modify the expression to return a specific
    56  type.
    57  
    58  ```expr
    59  let arr = [1, 2, 3]; int(arr[0])
    60  ```
    61  :::
    62  
    63  
    64  ## WithContext
    65  
    66  Although the compiled program is guaranteed to be terminated, some user defined functions may not be. For example, if a
    67  user defined function calls a remote service, we may want to pass a context to the function.
    68  
    69  This is possible via the [`WithContext`](https://pkg.go.dev/github.com/expr-lang/expr#WithContext) option.
    70  
    71  This option will modify function calls to include the context as the first argument (only if the function signature
    72  accepts a context).
    73  
    74  ```expr
    75  customFunc(42)
    76  // will be transformed to
    77  customFunc(ctx, 42)
    78  ```
    79  
    80  Function `expr.WithContext()` takes the name of context variable. The context variable must be defined in the environment.
    81  
    82  ```go
    83  env := map[string]any{
    84      "ctx": context.Background(),
    85  }
    86  
    87  program, err := expr.Compile(code, expr.Env(env), expr.WithContext("ctx"))
    88  ```
    89  
    90  ## ConstExpr
    91  
    92  For some user defined functions, we may want to evaluate the expression at compile time. This is possible via the
    93  [`ConstExpr`](https://pkg.go.dev/github.com/expr-lang/expr#ConstExpr) option. 
    94  
    95  ```go
    96  func fib(n int) int {
    97      if n <= 1 {
    98          return n
    99      }
   100      return fib(n-1) + fib(n-2)
   101  }
   102  
   103  env := map[string]any{
   104      "fib": fib,
   105  }
   106  
   107  program, err := expr.Compile(`fib(10)`, expr.Env(env), expr.ConstExpr("fib"))
   108  ```
   109  
   110  If all arguments of the function are constants, the function will be evaluated at compile time. The result of the function
   111  will be used as a constant in the expression.
   112  
   113  ```expr
   114  fib(10)    // will be transformed to 55 during the compilation
   115  fib(12+12) // will be transformed to 267914296 during the compilation
   116  fib(x)     // will **not** be transformed and will be evaluated at runtime
   117  ```
   118  
   119  ## Options
   120  
   121  Compiler options can be defined as an array:
   122  
   123  ```go
   124  options := []expr.Option{
   125      expr.Env(Env{})
   126      expr.AsInt(),
   127      expr.WarnOnAny(),
   128      expr.WithContext("ctx"),
   129      expr.ConstExpr("fib"),
   130  }
   131  
   132  program, err := expr.Compile(code, options...)
   133  ```
   134  
   135  Full list of available options can be found in the [pkg.go.dev](https://pkg.go.dev/github.com/expr-lang/expr#Option) documentation.