Skip to content

Kat script generator

finesse importer requested to merge feature/unparser into master

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 use modes maxtem=n for equivalent functionality.
  • Adds a required name argument to Operator. This is required so that the generator can figure out what function or operator it should dump for an Operator object.
  • Added explicit on_complete etc. arguments to axis actions like Xaxis, 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 to unparse, 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 represent None, which in kat script is none.
  • 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 and action.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

Merge request reports