# Built-in expression parser

Turing has a built-in mathematical expression parser, which is used when the program is in pseudocode mode.

The language is case-insensitive for keywords, i.e. `FALSE`, `false` and `FaLsE` are the same thing.

## Types

### Number

Stored using a Python `float`, automatically converted to `int` when needed.

A point (`.`) shall be used to separate the integer part from the fractional part.

#### Example

- `42`
- `3.1415`

### Boolean

Stored using a Python `bool`, automatically converted to Number when needed (only if strict mode is disabled).

#### Syntax

The following keywords are available:
- `TRUE` / `VRAI` : True value
- `FALSE` / `FAUX` : False value

### String

Stored using a Python `str` (Unicode).

A string is enclosed between double quotes (`"`). It is not possible yet to escape characters inside a string literal.

### List

Stored using a Python `list`, indices start at 0 (like in any real programming language. *Lua*, you should feel ashamed of yourself).

#### Operators

Certain operators can be applied on operands of type List.

##### `+` (Plus)

Concatenates two lists.

###### Examples

- `[1, 2, 3] + [3, 4, 5] == [1, 2, 3, 3, 4, 5]`

##### `-` (Binary minus)

Returns all items of A that are not in B.

###### Examples

- `[1, 2, 3] - [3, 4, 5] == [1, 2]`

##### `-` (Unary minus)

Returns a reversed copy of the list.

###### Examples

- `-[1, 2, 3] == [3, 2, 1]`

##### `*` (Times)

*Must be used on a List and a Number together.*

Duplicates the list the specified amount of times.

###### Examples

- `[1, 2, 3] * 3 == [1, 2, 3, 1, 2, 3, 1, 2, 3]`

##### `&` / `ET` (Intersection)

Returns all items of A that are also in B.

###### Examples

- `[1, 2, 3] & [2, 3, 4] == [2, 3]`

##### `|` / `OU` (Union)

Returns an ordered list of all items of A and all items of B, without duplicates.

###### Examples

- `[1, 2, 3] | [2, 3, 4] == [1, 2, 3, 4]`

##### `XOR` (exclusive Or)

Returns an ordered list of all items that are present either in A or B but not both.

###### Examples

- `[1, 2, 3] XOR [3, 4, 5] == [1, 2, 4, 5]`

### Function / lambda

Standard Python function.

#### Calling

A function call consists of the function followed by an argument list enclosed in parentheses. The function can be an identifier or any expression returning a function.

    someFunc(arg1, arg2, arg3)

The argument list can be passed as a list object, for example for dynamic calls, using the `*` expanding operator in front of the list object.

    gcd(*[248, 4584]) == gcd(248, 4584)

#### Lambda/inline function syntax

Comma-separated list of parameters enclosed in braces, followed by expression enclosed in parentheses. The function can be called immediately. There is no limit to the amount of parameters. A parameter is made of an identifier, no less, no more.

Varargs are not available yet.

##### Examples

- `{x, y}(2 * x + y)(3, 8) == 14`
- `map({a}(2 * a), [2, 3, 4]) == [4, 6, 8]`

## Operators

### Binary operators

| Symbol | Operator | Types |
|--------|----------|-------|
| `+` | Plus, Concatenate | Number, String, List |
| `-` | Minus, Reverse | Number, List |
| `*` | Times, Repeat | Number, List |
| `/` | Divide | Number |
| `%` | Modulus | Number |
| `^` | Power | Number |
| `<=` | Less than or equal | Number |
| `<` | Strictly less than | Number |
| `>` | Strictly greater than | Number |
| `>=` | Greater than or equal | Number |
| `==` | Equals | All |
| `!=` | Not equals | All |
| `&` / `ET` | AND / Intersection | Number, Boolean, List |
| | / `OU` | OR / Union | Number, Boolean, List |
| `XOR` | Exclusive OR / Exclusive union | Number, Boolean, List |

### Unary operators

| Symbol | Operator | Types |
|--------|----------|-------|
| `-` | Negate | Number, List |
| `NON` | Invert | Boolean |

The numbers and booleans are treated the same way as in **plain Python**. In other words, booleans can be treated as numbers (`False` becomes 0 and `True` becomes 1), and numbers can be treated as booleans (0 becomes `False` and everything else becomes `True).

If **strict mode** is enabled, operators can only be used with operands of **identical type**, and **implicit number-boolean casts** are disabled. The `c_bool` and `c_num` functions can then be used for that purpose.

## Function library

The engine provides many functions that can be used with almost all value types.

In the following table, a type name followed by a star (*) means that the function accepts a variable argument list of the specified self.

#### Example

The `average` function accepts either List(Number) or Number*. Thus, it can be used either with a list object: `average(myList)` or with varargs: `average(1, 2, 3)`.

| Name | Parameters | Description |
|------|------------|-------------|
| |**Basic**| |
|`abs`|

- `num` (Number)
|Returns the absolute value of `num`.|
|`arg` / `phase`|

- `x` (Number)
|Returns the argument (or phase) of `x`.|
|`ceil`|

- `num` (Number)
|Returns the smallest integer greater than or equal to `num`.|
|`conj`|

- `x` (Number)
|Returns the complex conjugate of `x`.|
|`derivative` / `deriv`|

- `func` (Function(Number))
- `h` (Number) default = 1e-07
|Returns the derivative of `func` (optional precision `h`).|
|`exp`|

- `num` (Number)
|Returns *e* to the power of `num`.|
|`floor`|

- `num` (Number)
|Returns the largest integer less than or equal to `num`.|
|`gcd` / `pgcd`|

- `a` (Integer)
- `b` (Integer)
|Returns the greatest common divisor of `a` and `b`.|
|`gradient`|

- `func` (Function(Number))
- `x` (Number)
- `h` (Number) default = 1e-07
|Returns the gradient of `func` at `x` (optional precision `h`).|
|`im`|

- `x` (Number)
|Returns the imaginary part of `x`.|
|`integrate` / `integ`|

- `func` (Function(Number))
- `a` (Number)
- `b` (Number)
- `steps` (Integer) default = 100000
|Returns the integral of `func` from `a` to `b` (optional number of steps: `steps`).|
|`lcm` / `ppcm`|

- `a` (Integer)
- `b` (Integer)
|Returns the least common multiple of `a` and `b`.|
|`ln`|

- `num` (Number)
|Returns the natural (base-*e*) logarithm of `num`.|
|`log`|

- `num` (Number)
- `b` (Number) != 0, default = e
|Returns the base-`b` logarithm of `num`.|
|`log10`|

- `num` (Number)
|Returns the base-10 logarithm of `num`.|
|`lower` / `minu`|

- `s` (String)
|Returns the lowercase version of `s`.|
|`polar` / `polaire`|

- `x` (Number)
|Returns a list containing the polar coordinates of `x`, respectively the modulus (radius) and argument (angle).|
|`pow` / `puiss`|

- `num` (Number)
- `p` (Number)
|Returns `num` to the `p`-th power.|
|`re`|

- `x` (Number)
|Returns the real part of `x`.|
|`rect`|

- `r` (Number)
- `phi` (Number)
|Converts the specified polar coordinates to a complex number.|
|`root`|

- `num` (Number)
- `n` (Number) != 0
|Returns the `n`-th root of `num`.|
|`round` / `arrondi`|

- `num` (Number)
- `prec` (Real)
|Rounds `num` to the nearest integer / (if specified) to `prec` decimals.|
|`sign`|

- `num` (Real)
|Returns the sign of `num` (-1 if negative, 1 if positive, 0 otherwise).|
|`sqrt` / `rac`|

- `num` (Number)
|Returns the square root of `num`. If `num` < 0, the result will be Complex.|
|`upper` / `maju`|

- `s` (String)
|Returns the uppercase version of `s`.|
| |**Geometry**| |
|`area_circle`|

- `radius` (Real)
|Returns the area of the circle with the specified `radius`.|
|`area_cube`|

- `side` (Real)
|Returns the surface area of the cube with the specified `side` length.|
|`area_cylinder`|

- `radius` (Real)
- `height` (Real)
|Returns the surface area of the cylinder with the specified `radius` and `height`.|
|`area_ellipse`|

- `r1` (Real)
- `r2` (Real)
|Returns the area of the ellipse with radii `r1` and `r2`.|
|`area_parallelepiped`|

- `a` (Real)
- `b` (Real)
- `c` (Real)
|Returns the surface area of the parallelogram with side lengths `a`, `b` and `c`.|
|`area_parallelogram`|

- `base` (Real)
- `height` (Real)
|Returns the area of the parallelogram with the specified `base` and `height`.|
|`area_polygon`|

- `sides` (Integer)
- `length` (Real)
|Returns the area of the regular polygon with the specified number of `sides` and side `length`.|
|`area_rectangle`|

- `s1` (Real)
- `s2` (Real)
|Returns the area of the rectangle with side lengths `s1` and `s2`.|
|`area_sector`|

- `radius` (Real)
- `angle` (Real)
|Returns the area of the circle sector with the specified `radius` and `angle`.|
|`area_sphere`|

- `radius` (Real)
|Returns the surface area of the sphere with the specified `radius`.|
|`area_square`|

- `side` (Real)
|Returns the area of the square with the specified `side` length.|
|`area_trapezoid`|

- `a` (Real)
- `b` (Real)
- `height` (Real)
|Returns the area of the trapezoid with sides `a` and `b` and height `height`.|
|`area_triangle`|

- `base` (Real)
- `height` (Real)
|Returns the area of the triangle with the specified base and height.|
|`area_triangle_sides`|

- `a` (Real)
- `b` (Real)
- `c` (Real)
|Returns the area of the triangle with the specified side lengths.|
|`peri_circle`|

- `radius` (Real)
|Returns the perimeter of the circle with the specified `radius`.|
|`vol_cube`|

- `side` (Real)
|Returns the volume of the cube with the specified `side` length.|
|`vol_cylinder`|

- `radius` (Real)
- `height` (Real)
|Returns the volume of the cylinder with the specified `radius` and `height`.|
|`vol_parallelepiped`|

- `a` (Real)
- `b` (Real)
- `c` (Real)
|Returns the volume of the parallelogram with side lengths `a`, `b` and `c`.|
|`vol_pyramid`|

- `sides` (Integer)
- `length` (Real)
- `height` (Real)
|Returns the volume of the regular pyramid with the specified number of `sides`, side `length` and `height`.|
|`vol_sphere`|

- `radius` (Real)
|Returns the volume of the sphere with the specified `radius`.|
| |**Statistics**| |
|`arithm_mean` / `moyenne` / `average`|

- `args` (List(Number))
|Returns the arithmetic mean of `args`.|
|`beta`|

- `a` (Number)
- `b` (Number)
|Returns the Beta function at `a` and `b`.|
|`binomial`|

- `n` (Number)
- `k` (Number)
|Returns the binomial coefficient for a subset of size `k` and a set of size `n`.|
|`choice` / `choix`|

- `args` (List(Any))
|Returns a random element from `args`.|
|`d_binomial`|

- `n` (Integer)
- `p` (Real) 0 <= p <= 1
- `k` (Integer)
|Returns the probability for `k` with the binomial distribution of parameters `n` and `p`.|
|`d_normal_cdf`|

- `mu` (Real)
- `sigma` (Real)
- `x` (Real)
|Returns the cumulative probability for `x` with the normal distribution of parameters µ=`mu` and σ=`sigma`.|
|`d_normal_cdf_inv`|

- `mu` (Real)
- `sigma` (Real)
- `p` (Real)
|Returns the number with cumulative probability `p` with the normal distribution of parameters µ=`mu` and σ=`sigma`.|
|`d_normal_pdf`|

- `mu` (Real)
- `sigma` (Real)
- `x` (Real)
|Returns the probability for `x` with the normal distribution of parameters µ=`mu` and σ=`sigma`.|
|`d_normal_std_cdf`|

- `x` (Real)
|Returns the cumulative probability for `x` with the standard normal distribution (µ=0 and σ=1).|
|`d_normal_std_cdf_inv`|

- `p` (Real)
|Returns the number with cumulative probability `p` with the standard normal distribution (µ=0 and σ=1).|
|`d_normal_std_pdf`|

- `x` (Real)
|Returns the probability for `x` with the standard normal distribution (µ=0 and σ=1).|
|`erf`|

- `x` (Number)
|Returns the error function at `x`.|
|`erfc`|

- `x` (Number)
|Returns the complementary error function at `x`.|
|`erfcinv`|

- `y` (Number)
|Returns the inverse of the complementary error function at `y`.|
|`erfinv`|

- `y` (Number)
|Returns the inverse of the error function at `y`.|
|`euler`|

- `n` (Integer)
|Returns the `n`-th Euler number.|
|`fact`|

- `x` (Integer)
|Returns the factorial of `x`.|
|`fib`|

- `n` (Integer)
|Returns the `n`-th Fibonacci number.|
|`filter` / `filtre`|

- `func` (Function(1 arg))
- `lst` (List)
|Returns a list containing all elements of `lst` for which `func` returns a truthy value.|
|`gamma`|

- `x` (Number)
|Returns the Gamma function at `x`.|
|`harmonic_mean` / `moyenne_harmo`|

- `args` (List(Number))
|Returns the harmonic mean of `args`.|
|`irange`|

- `start` (Number)
- `end` (Number)
- `step` (Number) default = 1
|Generates a list containing all number from `start` (inclusive) to `end` (inclusive) with a step of `step`.|
|`len` / `taille`|

- `T` (List)
|Returns the number of elements in `T`.|
|`log_gamma`|

- `x` (Number)
|Returns the natural logarithm of the absolute value of the Gamma function at `x`.|
|`map` / `appl`|

- `func` (Function(1 arg))
- `lst` (List)
|Applies `func` to each element of `lst` and returns the resulting list.|
|`max`|

- `args` (List(Number))
|Returns the maximum value of `args`.|
|`max_index`|

- `args` (List(Number))
|Returns the index of maximum value of `args`.|
|`median`|

- `lst` (List(Number))
|Returns the median of `lst`.|
|`min`|

- `args` (List(Number))
|Returns the minimum value of `args`.|
|`min_index`|

- `args` (List(Number))
|Returns the index of minimum value of `args`.|
|`mode`|

- `lst` (List(Number))
|Returns the mode of `lst`.|
|`randint` / `alea_ent`|

- `a` (Integer)
- `b` (Integer)
|Returns a random integer between `a` and `b` (inclusive).|
|`random` / `alea`|

- None
|Returns a random number between 0 (inclusive) and 1 (exclusive).|
|`range`|

- `start` (Number)
- `end` (Number)
- `step` (Number) default = 1
|Generates a list containing all number from `start` (inclusive) to `end` (exclusive) with a step of `step`.|
|`slice` / `tranche`|

- `lst` (List)
- `start` (Integer) 0 <= start <= end <= len(lst)
- `end` (Integer) start <= end <= len(lst)
|Returns a slice of the specified list, from index `start` (inclusive) to either index `end` (exclusive) or the end of the list.|
|`stand_dev` / `ecart_type`|

- `lst` (List(Number))
|Returns the population standard deviation of `lst`.|
|`stand_dev_sample` / `ecart_type_echant`|

- `lst` (List(Number))
|Returns the sample standard deviation of `lst`.|
|`sum`|

- `args` (List(Number))
|Returns the sum of all the terms of `args`.|
|`swap`|

- `T` (List)
- `a` (Integer)
- `b` (Integer)
|Swaps the elements of `t` at indices `a` and `b`.|
|`variance`|

- `lst` (List(Number))
|Returns the population variance of `lst`.|
|`variance_sample` / `variance_echant`|

- `lst` (List(Number))
|Returns the sample variance of `lst`.|
| |**Trigonometry**| |
|`acos`|

- `x` (Number)
|Returns the arc cosine of `x`.|
|`acosh`|

- `x` (Number)
|Returns the inverse hyperbolic cosine of `x`.|
|`acot`|

- `x` (Number)
|Returns the inverse cotangent of `x`.|
|`acoth`|

- `x` (Number)
|Returns the inverse hyperbolic cotangent of `x`.|
|`acsc`|

- `x` (Number)
|Returns the inverse cosecant of `x`.|
|`acsch`|

- `x` (Number)
|Returns the inverse hyperbolic cosecant of `x`.|
|`asec`|

- `x` (Number)
|Returns the inverse secant of `x`.|
|`asech`|

- `x` (Number)
|Returns the inverse hyperbolic secant of `x`.|
|`asin`|

- `x` (Number)
|Returns the arc sine of `x`.|
|`asinh`|

- `x` (Number)
|Returns the inverse hyperbolic sine of `x`.|
|`atan`|

- `x` (Number)
|Returns the arc tangent of `x`.|
|`atan2`|

- `y` (Number)
- `x` (Number)
|Returns the arc tangent of `y` / `x`.|
|`atanh`|

- `x` (Number)
|Returns the inverse hyperbolic tangent of `x`.|
|`chord` / `crd`|

- `x` (Number)
|Returns the chord of `x`.|
|`cos`|

- `x` (Number)
|Returns the cosine of `x`.|
|`cosh`|

- `x` (Number)
|Returns the hyperbolic cosine of `x`.|
|`cot`|

- `x` (Number)
|Returns the cotangent of `x`.|
|`coth`|

- `x` (Number)
|Returns the hyperbolic cotangent of `x`.|
|`covercos`|

- `x` (Number)
|Returns the coversed cosine of `x`.|
|`coversin`|

- `x` (Number)
|Returns the coversed sine of `x`.|
|`csc`|

- `x` (Number)
|Returns the cosecant of `x`.|
|`csch`|

- `x` (Number)
|Returns the hyperbolic cosecant of `x`.|
|`degrees` / `deg`|

- `x` (Number)
|Converts angle `x` from radians to degrees.|
|`excsc`|

- `x` (Number)
|Returns the excosecant of `x`.|
|`exsec`|

- `x` (Number)
|Returns the exsecant of `x`.|
|`hacovercos`|

- `x` (Number)
|Returns the hacoversed cosine of `x`.|
|`hacoversin`|

- `x` (Number)
|Returns the hacoversed sine of `x`.|
|`havercos`|

- `x` (Number)
|Returns the haversed cosine of `x`.|
|`haversin`|

- `x` (Number)
|Returns the haversed sine of `x`.|
|`hypot`|

- `x` (Number)
- `y` (Number)
|Returns the hypotenuse / Euclidean norm of the vector (`x`, `y`).|
|`radians` / `rad`|

- `x` (Number)
|Converts angle `x` from degrees to radians.|
|`sec`|

- `x` (Number)
|Returns the secant of `x`.|
|`sech`|

- `x` (Number)
|Returns the hyperbolic secant of `x`.|
|`sin`|

- `x` (Number)
|Returns the sine of `x`.|
|`sinc`|

- `x` (Number)
|Returns the cardinal sine of `x`.|
|`sinh`|

- `x` (Number)
|Returns the hyperbolic sine of `x`.|
|`tan`|

- `x` (Number)
|Returns the tangent of `x`.|
|`tanh`|

- `x` (Number)
|Returns the hyperbolic tangent of `x`.|
|`vercos`|

- `x` (Number)
|Returns the versed cosine of `x`.|
|`versin`|

- `x` (Number)
|Returns the versed sine of `x`.|
| |**Type conversion**| |
|`c_bool`|

- `obj` (Any)
|Tries to convert `obj` to Boolean.|
|`c_list`|

- `obj` (Any)
|Tries to convert `obj` to List.|
|`c_num`|

- `obj` (Any)
|Tries to convert `obj` to Number.|
|`c_str`|

- `obj` (Any)
|Converts `obj` to String.|


Useful (?) constants are also provided, with the maximum supported precision.

| Name | Approximated value | Description |
|------|-------------------:|-------------|
| |**Other constants**| |
|`e`|2.718281828459045|*e* - Euler number|
|`euler_gamma`|0.577215664901533|*γ* - Euler-Mascheroni constant|
|`i`|i|*i* - Imaginary unit|
|`inf`|inf|*∞* - Positive infinity|
|`khinchin`|2.685452001065306|*K0* - Khinchin's constant|
|`phi`|1.618033988749895|*φ* - Golden ratio|
| |**Physics**| |
|`celerity`|299792458|*c* - Speed of light in vacuum (m·s-1)|
|`gravity`|6.6740831·10-11|*G* - Gravitational constant (N·m2·kg-2)|
|`planck`|6.62607004081·10-34|*h* - Planck constant (J·s-1)|
|`planck_charge`|1.8755459·10-18|*qP* - Planck charge (C)|
|`planck_length`|1.61622938·10-35|*lP* - Planck length (m)|
|`planck_mass`|2.17647051·10-8|*mP* - Planck mass (kg)|
|`planck_temp`|1.41680833·1032|*TP* - Planck temperature (K)|
|`planck_time`|5.3911413·10-44|*tP* - Planck time (s)|
|`red_planck`|1.054571629·10-34|*ħ* - Reduced Planck constant (J·s-1)|
|`vacuum_imped`|376.730313461770663|*Z0* - Impedance of free space (Ω)|
|`vacuum_permea`|1.256637061435917·10-6|*μ0* - Vacuum permeability (N·A-2)|
|`vacuum_permit`|8.854187817620389·10-12|*ε0* - Vacuum permittivity (F·m-1)|
| |**Statistics**| |
|`catalan`|0.915965594177219|*G* - Catalan's constant|
|`glaisher`|1.282427129100623|*A* - Glaisher-Kinkelin constant|
| |**Trigonometry**| |
|`pi`|3.141592653589793|*π* - Perimeter of a circle of diameter 1|
|`tau`|6.283185307179586|*τ* - Double of π|

