Kat script generator
This MR adds a kat script generator to allow a model to be serialised to kat script. This has many uses but one of the most important will be to serialise the model state in analysis outputs (relevant: #89 (closed)).
The main addition to the public API is that you can now call unparse
and unparse_file
on a Model
to serialise it to kat script.
This also changes a few other bits of core code:
- Removes the
maxtem
command as discussed in #132 (closed). Users should usemodes maxtem=n
for equivalent functionality. - Adds a required
name
argument toOperator
. This is required so that the generator can figure out what function or operator it should dump for anOperator
object. - Added explicit
on_complete
etc. arguments to axis actions likeXaxis
, required for generation (see notes below).
Notes:
- There are two generator "modes": the default is to dump only the arguments for objects that are not set to their defaults. The second is an "archival" mode, enabled by specifying
full=True
in the call tounparse
, which dumps all available arguments even if they are their default values. This ensures changes to defaults later don't affect previously dumped scripts. This requires the introduction of a new token to representNone
, which in kat script isnone
. - Dumpable instructions (elements, actions, commands) whose Python equivalents define variadic arguments (
*args
and**kwargs
) must now define attributes matching those arguments (e.g.action.args
andaction.kwargs
). These are used to retrieve the arguments when dumping kat script for the action. There seems to be no easy way around this, since otherwise the generator would need to traverse the object's MRO to figure out what all the parameters are. - Each instruction defines templates representing themselves in kat-script. The first template is considered the canonical one, and is currently the only one actually used in dumping. We might later want to allow other forms of instruction to be dumped, such as with or without brackets, multiline, etc.
Tasks:
-
Two modes: human "readable" mode that dumps only set parameters (default), and an "archival" mode that dumps everything including empty parameters. -
Update docstrings of various new methods/classes/etc. -
Add unit tests for all supported instructions. -
Test operator precendence - made into separate issue since there's a bug - see #136 (closed) and #137 (closed) -
Add integration tests to check dumping then re-parsing results in same model. -
Test dumping of custom components, actions and commands. -
Get rid of maxtem
as per #132 (closed) -
Add issue about adding some docs for generating - see #138 (closed)
Edited by finesse importer