FAQ - Frequently Asked Questions

Why custom format? Why not json or xml or …?

In short: a custom ast format is used only to edit and store files. json format is also available and is a prefered format for processing asterix descriptions.

Users (author included) normally prefer standard formats like json or xml. However, for the purpose of editing and storing asterix specifications, a custom format is more convenient.

It is a form of a domain specific language with a lot of benefits. Comparing to json, the custom format is:

Compare for example the same definitions snippet

… in .ast

SAC "System Area Code"
    element 8
        raw

… and in .json format.

{
    "definition": null,
    "description": null,
    "name": "SAC",
    "remark": null,
    "spare": false,
    "title": "System Area Code",
    "variation": {
        "content": {
            "type": "Raw"
        },
        "size": 8,
        "type": "Element"
    }
}

Admittedly, the null values could be excluded, but the json definitions still contain a lot of overhead.

I do not like a converter in a processing chain.

This is reasonable, but in order to keep the definitions clean and correct, some form of a tool (editor, converter) can not be avoided.

Specifications need to be validated, which requires reading and parsing functions.

Also, when the definitions are written by hand (using a general purpose editor), there should be a mechanism to write a normalized version of a file (align indents, sort key/value pairs…).

In other words, reading and writing of the specs files is required, regardless of the format.

It is important to note that aspecs handles the conversion in a very safe way.

During automatic conversion process, it is verified that all supported formats generate the same file signature, which is a very strong assurance that all formats contain the same definitions.

The LSB numeric expression

The LSB (least significant bit) value is defined in the form of precise expression, instead of a decimal number. This is to avoid rounding error in specifications.

For example, the extreme case is item I062/105/LAT. It is defined as 180/2^25.

If specified as fixed digit decimal number, like 0.00000536442 or 5.364418029785156e-6 (more valid digits), some unexpected rounding error might occur. It is up to library implementation to decide the evaluation scenario and required precision. For example, the following recursive function can be used to convert from Number to a real value:

-- in haskell
evalNumber :: Fractional a => A.Number -> a
evalNumber = \case
    NumInt i -> fromIntegral i
    NumDiv a b -> evalNumber a / evalNumber b
    NumPow a b -> fromIntegral (a ^ b)
# in python if reading from 'json' format
def eval_number(value):
    t = value['type']
    if t == 'Integer':
        return float(value['value'])
    if t == 'Div':
        a = eval_number(value['numerator'])
        b = eval_number(value['denominator'])
        return a/b
    if t == 'Pow':
        return float(pow(value['base'], value['exponent']))
    raise Exception('unexpected value type {}'.format(t))

Some unsorted remarks about asterix

It is not strictly related to this project, but there are some facts about asterix which are worth mentioning. This might save you some time when implementing asterix encoder/decoder.