Client Classification/Debugging Expressions section needs clarification about tokens
The text in this section, specifically the part about tokens (included below), is confusing and would benefit from some additional context or clarification.
In order to understand the logging statements, one must understand a bit about how expressions are evaluated; for a more complete description refer to the design document at https://gitlab.isc.org/isc-projects/kea/wikis/design%20documents. In brief there are two structures used during the evaluation of an expression: a list of tokens which represent the expressions and a value stack which represents the values being manipulated.
The list of tokens is created when the configuration file is processed with most expressions and values being converted to a token. The list is organized in reverse Polish notation. During execution, the list will be traversed in order. As each token is executed it will be able to pop values from the top of the stack and eventually push its result on the top of the stack. Imagine the following expression:
"test": "substring(option.hex,0,3) == 'foo'",
This will result in the following tokens:
option, number (0), number (3), substring, text ('foo'), equals
In this example the first three tokens will simply push values onto the stack. The substring token will then remove those three values and compute a result that it places on the stack. The text option also places a value on the stack and finally the equals token removes the two tokens on the stack and places its result on the stack.
When debug logging is enabled, each time a token is evaluated it will emit a log message indicating the values of any objects that were popped off of the value stack and any objects that were pushed onto the value stack.
The values will be displayed as either text if the command is known to use text values or hexadecimal if the command either uses binary values or can manipulate either text or binary values. For expressions that pop multiple values off the stack, the values will be displayed in the order they were popped. For most expressions this won't matter but for the concat expression the values are displayed in reverse order from how they are written in the expression.