# OBITools expression language

Several OBITools (*e.g.* obigrep, obiannotate) allow the user to specify some simple expressions to compute values or define predicates. This expressions are parsed and evaluated using the [gval](https://pkg.go.dev/github.com/PaesslerAG/gval "Gval (Go eVALuate) for evaluating arbitrary expressions Go-like expressions.") go package, which allows for evaluating go-Like expression.

## Variables usable in the expression

- `sequence` is the sequence object on which the expression is evaluated.
- `annotations`is a map object containing every annotations associated to the currently processed sequence.

## Function defined in the language 

### Instrospection functions {.unnumbered}

- `len(x)`is a generic function allowing to retreive the size of a object. It returns 
  the length of a sequences, the number of element in a map like `annotations`, the number
  of elements in an array. The reurned value is an `int`.

### Cast functions {.unnumbered}

- `int(x)`  converts if possible the `x` value to an integer value. The function 
  returns an `int`.
- `numeric(x)` converts if possible the `x` value to a float value. The function 
  returns a `float`.
- `bool(x)` converts if possible the `x` value to a boolean value. The function 
  returns a `bool`.

### String related functions {.unnumbered}

- `printf(format,...)` allows to combine several values to build a string. `format` follows the
   classical C `printf` syntax. The function returns a `string`.
- `subspc(x)` substitutes every space in the `x` string by the underscore (`_`) character. The function 
   returns a `string`. 

## Accessing to the sequence annotations

The `annotations` variable is a map object containing all the annotations associated to the currently processed sequence. Index of the map are the attribute names. It exists to possibillities to retreive
an annotation. It is possible to use the classical `[]` indexing operator, putting the attribute name
quoted by double quotes between them. 

```go
annotations["direction"]
```

The above code retreives the `direction` annotation. A second notation using the dot (`.`) is often
more convenient.

```go
annotations.direction
```

Special attributes of the sequence are accessible only by dedicated methods of the `sequence` object.

- The sequence identifier : `Id()`
- THe sequence definition : `Definition()`


