Reorganization of the documentation book directory

Former-commit-id: 095acaf9c8649b0e527c6253dc79330feedac865

doc/book/expressions.qmd

@@ -0,0 +1,56 @@
+# 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()`
+
+