The Evaluator
The Evaluator is probably the most exciting and important feature in LCD4Linux. Basically, it's a subsystem which evaluates expressions and returns the result. Nearly everything in LCD4Linux passes the Evaluator, so you can use expressions for nearly everything!
An Expression is just a simple string. The result of an expression is a string, too. Internally, the Evaluator uses a two-way-representation of every value, it is stored as a string and as a floating point number (for mathematical calculations). Conversion between the two representations will be done on the fly: If a operation expects a numerical argument (e.g. an addition), but the argument is a string, it will be convertet to float, and vice versa.
If you want to pass a fixed string, you have to enclose it in single quotes (eg 'string'). Whithin this string, the evaluator knows about the default escape sequences like \a (bell) \b (backspace) \t (horizontal tab) \n (new line) \v (vertical tab) \f (form feed) \r (carriage ret). \\ will result in a single backslash, and if you want to use a single quote, you have to escape it as \' (otherwise the single quote will be handled as the end of the string).
Beside that you can use escape sequences to write characters in octal or hexadecimal notation. (Especially useful for notating special characters of your display.)
The octal notation is \ABC (exactly 3 octal digits 0..7 after the backslash). All valid sequences are substituted, all invalid sequences are unchanged.
The hexadecimal notation is \xAB (witch one or two hexadecimal digits 0..9, a..f or A..F). The Evaluator tries to substitude \xAB first. If that isn't valid it'll try to substitude \xA (B will be unchanged in this case). If none of them is valid, the sequence is unchanged. The sequences \x0 (followed by a non-hexadecimal character) or \x00 are deleted to avoid the premature termination of the string.
Example: A\102C, A\x42C could be used to notate 'ABC'.
Note that name (within single quotes) is a string, while name (without single quotes) is a variable!
The Evaluator knows Operators and Functions. Operators are hardcoded into the Evaluator, while Functions can be added at runtime. This is what Plugins do: They just add one or more functions to the Evaluator.
The Evaluator can be easily tested using LCD4Linux's interactive mode: Just run 'lcd4linux -i', and you will get a prompt where you can enter an expression (e.g. '2+3'), and the result will be displayed (e.g. '5'). This is very handy for testing plugins! To quit interactive mode, just press Ctrl-D.
Operators
| Token | Description | Example | Result | ||
| + | addition | 2 + 3 | 5 | ||
| - | subtraction or sign | 2 - 3 | -1 | ||
| . | string concatenation | 'Hi' . ' ' . 'there' | 'Hi there' | ||
| * | multiplication | 2 * 3 | 6 | ||
| / | division | 6 / 2 | 3 | ||
| % | modulo | 5 % 2 | 1 | ||
| ! |power| 2!3 | 8 | ||||
| == | numeric equal | 2 == 3 | 0 | ||
| != | numeric not equal | 2 != 3 | 1 | ||
| < | numeric less than | 2 < 3 | 1 | ||
| ⇐ | numeric less or equal | 2 ⇐ 3 | 1 | ||
| > | numeric greater than | 2 > 3 | 0 | ||
| >= | numeric greater or equal | 2 >= 3 | 0 | ||
| eq | string equal | 'lcd' eq 'linux' | 0 | ||
| ne | string not equal | 'lcd' ne 'linux' | 1 | ||
| lt | string less than | 'lcd' lt 'linux' | 1 | ||
| le | string less or equal | 'lcd' le 'linux' | 1 | ||
| gt | string greater than | 'lcd' gt 'linux' | 0 | ||
| ge | string greater or equal | 'lcd' ge 'linux' | 0 | ||
| ! | logical NOT | !0 | 1 | ||
| logical OR | 1 | 0 | 1 | ||
| & | logical AND | 1 & 0 | 0 | ||
| ( ) | opening/closing brace | 2 * (3 + 4) | 14 | ||
| = | variable assignements | a=2+3 | 5 | ||
| ? : | conditional a?b:c | a > 1024 ? 'kB' : 'MB' | 'kB' | ||
| ; | expression lists | 2+3;2*3 | 6 | ||
| , | comma (argument seperator) | func (2, 3) |
Functions
The Evaluator does not have any built-in functions, but such functions are added by plugins. A plugin can be an explicit one, but display drivers can add functions, too (all specific display features are implemented as plugins, e.g. contrast, backlight, GPO's, temperature sensors, fan speed reading and setting, and so on). This is described in detail in the corresponding display driver documentation.
Functions can have a fixed or variable number of parameters; this depends on the implementation, and is described in detail in the corresponding documentation.
Functions usually return something, but they can have side-effects, too: a function can set or control something, or trigger an action (e.g. if your display has a software-controlled backlight, this is implemented as a function, usually with variable parameters: LCD::backlight() returns the current backlight level, while LCD::backlight(n) sets the backlight to n)