Usage¶
Running yace requires that you have:
Installed yace and auxilary Tools
A Interface Definition file describing your C API or a Yace-compatible C-header
To satisfy the first point, then see Install. For the second point, then you can consult Interface Definition for reference to define a Storage Format from scratch.
Command-Line Interface¶
Invoking the command-line interface of yace:
yace --help
looks like
usage: yace [-h] [--emit {capi,ctypes} [{capi,ctypes} ...]] [--version]
[--output OUTPUT] [--log-level]
filepath [filepath ...]
positional arguments:
filepath path to one or more Yace-file(s) or C Header(s)
options:
-h, --help show this help message and exit
--emit {capi,ctypes} [{capi,ctypes} ...]
treat filepath(s) as Yace-file, and emit code using
target(s), then exit
--version show program's version number and exit
--output OUTPUT path to output directory, for emitted code / artifacts
--log-level, -l increase log-level.
Note
Notice that unless an error occurs then yace is silent. To make yace
chatty, then increase the log-level using the arguments: -l / -ll /
-lll.
Example¶
To get a quick sense of yace then you can utilize this simple example:
../../../models/example.yaml¶
---
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}
With it, invoke yace like so:
yace models/example.yaml --emit capi ctypes --output output
yace will then populate the output-directory output with the following
emitted code and artifacts:
output
├── capi
│ ├── a.out
│ ├── clang-format-c.clang-format
│ ├── clang-format-h.clang-format
│ ├── clang-format.log
│ ├── doxygen.conf
│ ├── doxygen.log
│ ├── doxyreport
│ ├── foo_check.c
│ ├── foo_pp.c
│ ├── gcc.log
│ ├── libfoo.h
│ ├── libfoo_core.h
│ └── libfoo_pp.h
├── ctypes
│ ├── black.log
│ ├── ctypes_sugar.py
│ ├── foo.py
│ ├── foo_check.py
│ ├── isort.log
│ └── python3.log
└── example.yaml
3 directories, 19 files
Example: capi¶
The C API header generated from the above looks like:
../../../output/capi/libfoo_core.h¶
/**
* foo; Core API
*
* Brief Description
*
* Full Description
*
* ------------------------------------------------------------------------------------------------
* Copyright (C) Foo Bar <foo@example.com>
* SPDX-License-Identifier: Unknown License
*
* @file libfoo.h
* ------------------------------------------------------------------------------------------------
* NOTE: This file is created using yace: https://github.com/safl/yace
*/
#define PLOT_SERIAL "WYRD1234"
#define PLOT_FOO 0xACDC
#define PLOT_VERSION_MAJOR 1
#define PLOT_VERSION_MINOR 2
#define PLOT_VERSION_PATCH 3
/**
* Description of enum
*
* 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.
*
* @enum plot_options
*/
enum plot_options {
PLOT_OPTIONS_PNG = 0x1, ///< First thing
PLOT_OPTIONS_PDF = 0x2, ///< Second thing
};
/**
* Description of structure
*
* @struct coordinate
*/
struct coordinate {
int32_t x; ///< X Coordinate
int32_t y; ///< Y Coordinate
int32_t z; ///< Z Coordinate
};
/**
* Description of a feature...
*
* @union feature
*/
union feature {
struct coordinate coord; ///< Coordinate
uint32_t vector; ///< Vector
};
/**
* This is a function
*
* @param x The first thing
* @param y The second thing
*
* @return {'Something': 'on success, -1 on error.'}
*/
int
foo(int x, int y);
/**
* This is a function pointer prototype
*
* @param x The first thing
* @param y The second thing
*
* @return {'Something': 'on success, -1 on error.'}
*/
typedef int (*binop_func)(int x, int y);
The emitted C header above has been modified by clang-format after it was
emitted. This is one of the stages that a yace target goes through by
default.
Example: ctypes¶
The ctypes target produces the following:
../../../output/ctypes/foo.py¶
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
Brief Description
Full Description
Copyright (C) Foo Bar <foo@example.com>
SPDX-License-Identifier: Unknown License
-------------------------------------------------------------------------------
NOTE: This file was generated using yace: https://github.com/safl/yace
"""
from ctypes_sugar import Enum, Structure, Union
Note, this is early stage of the ctypes target.
Additional Examples¶
For more elaborate examples, then take a look at:
The irs in the yace repository at https://github.com/safl/yace/tree/main/models
The target-specific output in the Targets section
The artifacts produces on the GitHUB Actions Page