This document describes the life-cycle of CASText2 evaluation. Use this when you need to decide what to do and when and want to use CASText to do it.
In the first phase of the life-cycle CASText is just a string that may or may not contain CASText specific syntax, like blocks or injections. This is the format authors use when writing question-text or feedback or even inline CASText. If you are a developer of the STACK core you are probably only focused on turning this to the next forms, or maybe you are using inline CASText to build something and leave processing it further to tools that do it.
Inline CASText is not actually a part of the life-cycle it is just a way of injecting raw CASText into places and it relies on compile time processing to turn it to usable compiled CASText.
The second phase of the life-cycle is the compiled form of the CASText, this is the result of raw CASText being parsed and then turned into a CAS statement. This happens by asking all the blocks present in the CASText to convert the parts of the parse tree related to them into statements and joining those together. Caching the compilation result is something we really want to do as recompiling is pointless and for large documents can take quite a lot of time, as the compilation result will always be the same for a given raw CASText in the same context (context variance does not yet exist, but may become a thing) i.e. same place in the question after same keyvals and so on, this caching does not depend on the question variant and can be shared by all variants.
Simplification and other pre-processing
The compiled CASText statement is then further processed as far as it can be without actually evaluating it in CAS. This processing can lead into a situation where the statement simplifies to a single string which essentially means that the value of evaluating that statement is going to be the same as the statement itself, in this special case it is unnecessary to send that statement to the CAS for evaluation.
During this pre-processing it is also possible to extract long static string values that do not take part in the logic from the statement and replace them with shorter placeholders. These static strings are then stored separately and can be returned to their places after evaluation.
By evaluating the compiled CASText statement in the CAS we get evaluated CASText which is essentially either a raw string value or a nested list describing which blocks need to post-process things and which parameter values they should use when doing that. This intermediate result is something that the CAS cache can hold onto as an usable value for the next step.
After the CASText has been evaluated and the evaluated CASText has had any static strings restored to their places we ask all the blocks that are declared in the evaluated value to do their post-processing. They turn the nested list structure into a flat string which we may then present to the user if need be. It is important to note that this post-processing may not be side effect free and some blocks may for example inject scripts into the page, so simply caching the end result of this rendering is not a viable solution as it might miss those side effects. In general, it is best to apply lazy evaluation to this and only post-process evaluated CASText into rendered CASText if the rendering actually needs to be displayed, while the rendering is often the cheapest operations of this whole life cycle it will always save some resources.
If you are not going to render something, why evaluate it at all? This might be something that comes to mind, especially related to PRTs, the primary reason being that the CAS-cache can efficiently hold onto those evaluated CASText segments and if the only difference between the evaluated CASSessions is it necessary to generate two different sessions to cache? Note that that caching would happen both at CAS-cache database table and in the parser cache for the result. Also note that at the point where you would need to know whether you are to actually render things to decide whether to evaluate them it might not be easily knowable whether to do so, and minimising branching is always a good idea.
Some blocks need additional context information to be evaluated e.g. the
[[lang]]-block needs a special variable to be set to the language selected for presentation. Do not forget to set such things if you use such blocks.