The safest advice about editing the textual output from astWriteastWrite (or
astShowastShow) is “don't!”—unless you know what you are doing.
Having given that warning, however, it is sometimes possible to make
changes to the text, or even to write entire ObjectObject descriptions from
scratch, and to read the results back in to construct new
Objects. Normally, simple changes to numerical values are safest, but
be aware that this is a back door method of creating Objects, so
you are on your own! There are a number of potential pitfalls. In
particular:
- astReadastRead is intended for retrieving data written by astWrite and
not for reading data input by humans. As such, the data validation
provided is very limited and is certainly not foolproof. This makes it
quite easy to construct Objects that are internally inconsistent by
this means. In contrast, the normal programming interface incorporates
numerous checks designed to make it impossible to construct invalid
Objects. You should not necessarily think you have found a bug if your
changes to an Object's textual description fail to produce the results
you expected!
- In many instances the names associated with values in textual
output will correspond with Object attributes. Sometimes, however,
these names may differ from the attribute name. This is mainly because
of length restrictions imposed by other common external formats, such
as FITS headers. Some of the names used do not correspond with
attributes at all.
- It is safest to change single numerical or string values.
Beware of changing the size or shape of Objects (e.g. the
number of axes in a FrameFrame). Often, these values must match others
stored elsewhere within the Object and changing them in a haphazard
fashion will not produce useful results.
- Be wary about un-commenting default values. Sometimes this will
work, but often these values are derived from other Objects stored
more deeply in the structure and the proper place to insert a new
value is not where the default itself appears.