Specify pointer attributes in `api.json`

[Parzival-3141]

Extracted from #116.
See also: orca-app/orca-zig#7.

Add an attributes field to pointer types, containing an array of strings signalling how the pointer is to be used:

"name": "str",
"doc": "A null-terminated string.",
"type": {
    "kind": "pointer",
    "attributes": ["many-item", "const", "null-terminated"],
    "type": {
        "kind": "char"
    }
}

Pointer attributes are treated like flags. The lack of an attribute in the array is the same as saying it's opposite is true (e.g. if nullable is not present, then the pointer must not be null). To simplify parsing, the attributes field must always be present, even if empty. This behaviour is similar to function parameters.

Existing attr fields will be converted to the new attribute format as well.

Here are the proposed pointer attributes:

• many-item:
  • Enabled: points to an unknown number of items.
  • Disabled: points to a single item.
  • Use case: arrays, strings, buffers.
• const:
  • Enabled: points to an immutable item.
  • Disabled: points to a mutable item.
  • Use case: signaling that functions will or will not modify parameters passed by reference.
• nullable:
  • Enabled: pointer may be null.
  • Disabled: pointer cannot be null.
  • Use case: signaling what input is valid to a function or how to deal with it's output. Functions should assert non-nullable parameters are not null.
• null-terminated:
  • Enabled: pointer's length is determined by a null sentinel value. many-item must be present as well.
  • Disabled: pointer has no sentinel value.
  • Use case: C strings.

The naming for const is a little confusing, since the subject is the child type rather than the pointer itself (unlike the other attributes). However I don't think it'll matter as long as the documentation is clear.

Effects

If implemented, the orca-zig project can make use of this feature to drastically improve type safety in it's bindings. I'm not as familiar with Odin, but I assume it's bindings will see similar benefits. Orca can also use this metadata to annotate the C headers, improving API clarity for C users too.

[martinfouilleul]

I like the idea of annotating pointers. Mutability and nullability seem well-served with flags, but many-item and null-terminated would be better covered by a single length (or similar name) field that would describe how to do the bounds-checking.

I've done something similar for the native-to-wasm bindings specs in src/wasmbind/gles_api.json, where len can be:

• "len": { "count": "paramName"} when the number of elements is held by another param.
• "len": {"components": n} when the number of elements is statically known (in GL apis, that would be e.g. vectors expressed as an array components).
• (The two above can be combined "len": {"components": 4, "count": "n"} for an array of floats describing n 4D vectors.)
• "len": {"proc": "procName", "args": [ param list ]} where the pointer length can be computed by passing other parameters to a procedure called procName.

This was just a quick way of generating bounds check on the GLES API, so I'm sure you can come up with a better version.

(Also I'd like to unify the schemas for both our C apis description and our native-to-wasm bindings generator, if this is something you want to help with)