Storage Format

In Yace, the C API and FFI are defined by a Yace-file. The content of a Yace-file is described in the following sections. Yace-file can be written manually, or with assistance from other tools, such as the C Parser.

The storage format for the Yace Interface Defitinion is in YAML. Thus, no extra tooling for linting and visualizing it, just use regular formaters and visualization tools such as jless. The content is validated when loaded.

The descriptions inside the Yace-file consists of meta-data and then descriptions of symbolic constants, data types, derived types, and function types. These are referred to as Entities and a Entity Listing for quick lookup is also available.

Files

A Yace Interface Definition File, is an YAML formated document where some keys in the document have special meaning. This is what one might call an interface definition language (idl). By design this is similar to the module definitions you find in projects like swig.

However, unlike other irs, then Yace does not define a new grammer that you have to learn. Rather it is object-oriented description of the entities formated in YAML. Each document in a Yace file thus refers to a class described in Entities.

Example

The key meta is a special key described in greater detail in the yace.ir.ir.Meta.

The remainder of a yace file consists of entities, under a key. These top-level keys have no special meaning / signifinance, they are there to serve as a means to organize the document. Conceptually, see all the top-level keys as “section-headers” in the document.

---
entities:
- ant: {}
  key: define
  sym: PLOT_SERIAL
  val:
    ant: {}
    key: str
    lit: WYRD1234
- ant: {}
  key: define
  sym: PLOT_FOO
  val:
    ant: {}
    key: hex
    lit: 44252
- ant: {}
  key: define
  sym: PLOT_VERSION_MAJOR
  val:
    ant: {}
    key: dec
    lit: 1
- ant: {}
  key: define
  sym: PLOT_VERSION_MINOR
  val:
    ant: {}
    key: dec
    lit: 2
- ant: {}
  key: define
  sym: PLOT_VERSION_PATCH
  val:
    ant: {}
    key: dec
    lit: 3
- ant: {}
  doc:
    brief: Description of enum
    description: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque accumsan massa est, ut ullamcorper
      lectus malesuada sit amet. Donec gravida nibh aliquam mattis rhoncus. Quisque sollicitudin ultricies orci, condimentum
      blandit lorem feugiat at. Aliquam tempus metus et nulla eleifend, eu dapibus risus pellentesque. Duis fermentum bibendum
      ligula in pharetra. Curabitur eget urna tempus, tempor dui sed, tempus lorem. Phasellus eu aliquam neque.
    tags:
      enum: {plot_options: ''}
  key: enum
  members:
  - ant: {}
    doc:
      brief: First thing
      description: ''
      tags: {}
    key: enum_value
    sym: PLOT_OPTIONS_PNG
    val:
      ant: {}
      key: dec
      lit: 1
  - ant: {}
    doc:
      brief: Second thing
      description: ''
      tags: {}
    key: enum_value
    sym: PLOT_OPTIONS_PDF
    val:
      ant: {}
      key: dec
      lit: 2
  sym: plot_options
- ant: {}
  doc:
    brief: Description of structure
    description: ''
    tags:
      struct: {coordinate: ''}
  key: struct_decl
  members:
  - ant: {}
    doc:
      brief: X Coordinate
      description: ''
      tags: {}
    key: field_decl
    sym: x
    typ:
      ant: {}
      array: false
      array_length: 0
      boolean: false
      canonical: int32_t
      character: false
      const: false
      enum: false
      integer: true
      key: i32_tspec
      pointer: false
      real: false
      signed: true
      size: false
      static: false
      struct: false
      union: false
      unsigned: false
      void: false
      width: 32
      width_fixed: true
  - ant: {}
    doc:
      brief: Y Coordinate
      description: ''
      tags: {}
    key: field_decl
    sym: y
    typ:
      ant: {}
      array: false
      array_length: 0
      boolean: false
      canonical: int32_t
      character: false
      const: false
      enum: false
      integer: true
      key: i32_tspec
      pointer: false
      real: false
      signed: true
      size: false
      static: false
      struct: false
      union: false
      unsigned: false
      void: false
      width: 32
      width_fixed: true
  - ant: {}
    doc:
      brief: Z Coordinate
      description: ''
      tags: {}
    key: field_decl
    sym: z
    typ:
      ant: {}
      array: false
      array_length: 0
      boolean: false
      canonical: int32_t
      character: false
      const: false
      enum: false
      integer: true
      key: i32_tspec
      pointer: false
      real: false
      signed: true
      size: false
      static: false
      struct: false
      union: false
      unsigned: false
      void: false
      width: 32
      width_fixed: true
  sym: coordinate
- ant: {}
  doc:
    brief: Description of a feature...
    description: ''
    tags:
      union: {feature: ''}
  key: union_decl
  members:
  - ant: {}
    doc:
      brief: Coordinate
      description: ''
      tags: {}
    key: field_decl
    sym: coord
    typ:
      ant: {}
      array: false
      array_length: 0
      boolean: false
      canonical: struct coordinate
      character: false
      const: false
      enum: false
      integer: false
      key: record_tspec
      pointer: false
      real: false
      signed: true
      size: false
      static: false
      struct: true
      sym: coordinate
      union: false
      unsigned: false
      void: false
      width_fixed: false
  - ant: {}
    doc:
      brief: Vector
      description: ''
      tags: {}
    key: field_decl
    sym: vector
    typ:
      ant: {}
      array: false
      array_length: 0
      boolean: false
      canonical: uint32_t
      character: false
      const: false
      enum: false
      integer: true
      key: u32_tspec
      pointer: false
      real: false
      signed: false
      size: false
      static: false
      struct: false
      union: false
      unsigned: true
      void: false
      width: 32
      width_fixed: true
  sym: feature
- ant: {}
  doc:
    brief: This is a function
    description: ''
    tags:
      param: {x: The first thing, y: The second thing}
      return: {Something: 'on success, -1 on error.'}
  key: function_decl
  parameters:
  - ant: {}
    key: parameter_decl
    sym: x
    typ:
      ant: {}
      array: false
      array_length: 0
      boolean: false
      canonical: int
      character: false
      const: false
      enum: false
      integer: true
      key: i_tspec
      pointer: false
      real: false
      signed: true
      size: false
      static: false
      struct: false
      union: false
      unsigned: false
      void: false
      width: 16
      width_fixed: false
  - ant: {}
    key: parameter_decl
    sym: y
    typ:
      ant: {}
      array: false
      array_length: 0
      boolean: false
      canonical: int
      character: false
      const: false
      enum: false
      integer: true
      key: i_tspec
      pointer: false
      real: false
      signed: true
      size: false
      static: false
      struct: false
      union: false
      unsigned: false
      void: false
      width: 16
      width_fixed: false
  ret:
    ant: {}
    array: false
    array_length: 0
    boolean: false
    canonical: int
    character: false
    const: false
    enum: false
    integer: true
    key: i_tspec
    pointer: false
    real: false
    signed: true
    size: false
    static: false
    struct: false
    union: false
    unsigned: false
    void: false
    width: 16
    width_fixed: false
  sym: foo
- ant: {}
  doc:
    brief: This is a function pointer prototype
    description: ''
    tags:
      param: {x: The first thing, y: The second thing}
      return: {Something: 'on success, -1 on error.'}
  key: function_pointer_decl
  parameters:
  - ant: {}
    key: parameter_decl
    sym: x
    typ:
      ant: {}
      array: false
      array_length: 0
      boolean: false
      canonical: int
      character: false
      const: false
      enum: false
      integer: true
      key: i_tspec
      pointer: false
      real: false
      signed: true
      size: false
      static: false
      struct: false
      union: false
      unsigned: false
      void: false
      width: 16
      width_fixed: false
  - ant: {}
    key: parameter_decl
    sym: y
    typ:
      ant: {}
      array: false
      array_length: 0
      boolean: false
      canonical: int
      character: false
      const: false
      enum: false
      integer: true
      key: i_tspec
      pointer: false
      real: false
      signed: true
      size: false
      static: false
      struct: false
      union: false
      unsigned: false
      void: false
      width: 16
      width_fixed: false
  ret:
    ant: {}
    array: false
    array_length: 0
    boolean: false
    canonical: int
    character: false
    const: false
    enum: false
    integer: true
    key: i_tspec
    pointer: false
    real: false
    signed: true
    size: false
    static: false
    struct: false
    union: false
    unsigned: false
    void: false
    width: 16
    width_fixed: false
  sym: binop_func
meta: {author: Foo Bar <foo@example.com>, brief: Brief Description, full: Full Description, lic: Unknown License, prefix: foo,
  project: foo, version: 0.0.1}

Entities

At the top-level only meta is a special key, however, in the documents representing interface/language symbols there are several special keys. The primary one is cls which defines the specific entity the document irs.

cls, all entities have this key, it is the string identifier of the class in the Entities.

dtype, this is a member of an entity which has a yace.ir.datatypes.Datatype member. It can be a string in shorthand-form with the cls identifier of the datatype. For example: dtype: u32 or in the full form: dtype: {cls: u32, pointer: 1}. The full explicit form is intended for adding attributes such as pointer, const, array.

lit, this is a special literal-key. For those entities which have it, then it can be provided in implicit short-form: lit: 10 or the explicit expansion lit: {cls: dec, val: 10}. The explicit long-form is useful for expressing literals which are not trivially represented such as lit: {cls: hex, val: 10}.

The following sections will cover the different entities.