OMG IDL schema parser

> _OMG IDL parser to flattened message definitions for (de)serialization_


This package provides functions to parse raw .idl schemas into resolved, flattened message definitions.

Output definitions can be passed to serializers along with a specified root schema name string in @foxglove/omgidl-serialization to read and write CDR, XCDR1 and XCDR2 messages.

Example

``TypeScript

const schemaString =
// Generated by https://github.com/foxglove/schemas

module foxglove {
// A vector in 3D space that represents a direction only
struct Vector3 {
double x;
double y;
double z;
};
};

module foxglove {
struct Quaternion {
double x;
double y;
double z;
@default(1.0)
double w;
};
};

module foxglove {
// A position and orientation for an object or reference frame in 3D space
struct Pose {
// Point denoting position in 3D space
Vector3 position;
// Quaternion denoting orientation in 3D space
Quaternion orientation;
};
};
;

const definitions = parseIDL(schemaString);
`

definitions results in:

`JavaScript
[
{
name: "foxglove::Vector3",
aggregatedKind: "struct",
definitions: [
{
name: "x",
isComplex: false,
type: "float64",
},
{
name: "y",
isComplex: false,
type: "float64",
},
{
name: "z",
isComplex: false,
type: "float64",
},
],
},
{
name: "foxglove::Quaternion",
aggregatedKind: "struct",
definitions: [
{
name: "x",
isComplex: false,
type: "float64",
},
{
name: "y",
isComplex: false,
type: "float64",
},
{
name: "z",
isComplex: false,
type: "float64",
},
{
name: "w",
annotations: {
default: {
name: "default",
type: "const-param",
value: 1,
},
},
defaultValue: 1,
isComplex: false,
type: "float64",
},
],
},
{
name: "foxglove::Pose",
aggregatedKind: "struct",
definitions: [
{
isComplex: true,
name: "position",
type: "foxglove::Vector3",
},
{
isComplex: true,
name: "orientation",
type: "foxglove::Quaternion",
},
],
},
]
`

API

parseIDL(schema: string) - parses raw .idl schema string to resolved, flattened definitions.

TypeScript types for the output definitions are also available.

OMG IDL Subset Support

NOTE: numbers like 7.4.1 refer to sections of the OMG IDL specification.

- Generally supported features

- 7.4.1 Building Block Core Data Types (with exceptions below)
- support for extended numeric types uint8, int8 ... uint64, int64
- Note 7.4.13 Building Block Extended Data-Types is not fully supported
- Literals (with some hexadecimal, character and wide-type exceptions)
- Blanks, horizontal and vertical tabs, newlines, form feeds, and comments (collective, "white space") as described below are ignored except as they serve to separate tokens
- Parse generic annotations (only defaultValue is read in to AST)
- unions and cases
- enumerator overrides with @value annotation
- All XCDR extensibility types: @final, @appendable, and @mutable
- const Color color = RED; and const Color color = Color::RED; are supported.

- Unsupported features

- native declarations
- forward declarations
- Constant expressions
- unary operators (outside of positive/negative numbers)
- default value annotation type checking
- identifiers prefixed with :: scope
- aggregated type inheritance
- Annotation definitions
- Built-in enums from annotations (like @autoid's HASH and SEQUENTIAL enums)
- Map types
- @autoid(HASH) on mutable aggregated types
- 7.2.6.1 - Octal integers are not supported (014)
- 7.2.6.2.1 wide character and wide string has limited support
- can be read in to schema but only considered uint8
- wide character and string literals are not supported (L'X')
- 7.2.6.3 - wide string literals are not supported
- 7.2.3.1 - we do not check collision explicitly and we use case-sensitive identifiers whereas IDL requires identifiers to be case insensitive. WARNING: This can cause incorrect reading of messages.
- 7.4.2-7.4.16` extended IDL building blocks not supported
- Composing variable-sized array typedefs with other array typedefs or struct member nodes.

- Unsupported reference and type resolution features
- numeric type checking for constant usage. This means that if you use a mis-typed constant it could cause message read errors or the mismatched type will show up in the deserialized message.
- we do not enforce type-based value ranges on constants in schema