Skip to content

Commit 9cbb459

Browse files
gmarcosbgmarcosb
committed
Add support for typedef, which allows clusters/structs to create distinct types that aliases to the raw type for better readability & documentation-by-code, e.g. IDs
1 parent 8e4ff10 commit 9cbb459

File tree

33 files changed

+1353
-84
lines changed

33 files changed

+1353
-84
lines changed

‎docs/api.md‎

Lines changed: 412 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/helpers.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3322,12 +3322,15 @@ This module contains the API for templating. For more detailed instructions, rea
33223322
* [~zcl_bitmaps(options)](#module_Templating API_ static zcl helpers..zcl_bitmaps) ⇒
33233323
* [~zcl_bitmap_items(options)](#module_Templating API_ static zcl helpers..zcl_bitmap_items)
33243324
* [~zcl_enums(options)](#module_Templating API_ static zcl helpers..zcl_enums) ⇒
3325+
* [~zcl_typedefs(options)](#module_Templating API_ static zcl helpers..zcl_typedefs) ⇒
33253326
* [~zcl_structs(options)](#module_Templating API_ static zcl helpers..zcl_structs) ⇒
33263327
* [~zcl_enum_items(options)](#module_Templating API_ static zcl helpers..zcl_enum_items)
33273328
* [~first_unused_enum_value(options)](#module_Templating API_ static zcl helpers..first_unused_enum_value) ⇒
33283329
* [~zcl_struct_items(options)](#module_Templating API_ static zcl helpers..zcl_struct_items) ⇒
33293330
* [~zcl_struct_items_by_struct_name(name, options)](#module_Templating API_ static zcl helpers..zcl_struct_items_by_struct_name) ⇒
33303331
* [~zcl_struct_items_by_struct_and_cluster_name(name, clusterName, options)](#module_Templating API_ static zcl helpers..zcl_struct_items_by_struct_and_cluster_name) ⇒
3332+
* [~zcl_typedef_by_typedef(name, options)](#module_Templating API_ static zcl helpers..zcl_typedef_by_typedef) ⇒
3333+
* [~zcl_typedef_by_typedef_and_cluster_name(name, clusterName, options)](#module_Templating API_ static zcl helpers..zcl_typedef_by_typedef_and_cluster_name) ⇒
33313334
* [~zcl_device_types(options)](#module_Templating API_ static zcl helpers..zcl_device_types) ⇒
33323335
* [~zcl_device_type_clusters(options)](#module_Templating API_ static zcl helpers..zcl_device_type_clusters) ⇒
33333336
* [~zcl_device_type_cluster_commands(options)](#module_Templating API_ static zcl helpers..zcl_device_type_cluster_commands) ⇒
@@ -3357,6 +3360,7 @@ This module contains the API for templating. For more detailed instructions, rea
33573360
* [~zcl_command_arguments(options)](#module_Templating API_ static zcl helpers..zcl_command_arguments) ⇒
33583361
* [~zcl_event_fields(options)](#module_Templating API_ static zcl helpers..zcl_event_fields)
33593362
* [~zcl_command_argument_data_type(typeName, options)](#module_Templating API_ static zcl helpers..zcl_command_argument_data_type)
3363+
* [~asResolvedUnderlyingZclType()](#module_Templating API_ static zcl helpers..asResolvedUnderlyingZclType)
33603364
* [~asUnderlyingZclType(typeName, options)](#module_Templating API_ static zcl helpers..asUnderlyingZclType)
33613365
* [~zcl_string_type_return(type, options)](#module_Templating API_ static zcl helpers..zcl_string_type_return)
33623366
* [~is_zcl_string(type)](#module_Templating API_ static zcl helpers..is_zcl_string)
@@ -3370,6 +3374,7 @@ This module contains the API for templating. For more detailed instructions, rea
33703374
* [~if_is_bitmap(type)](#module_Templating API_ static zcl helpers..if_is_bitmap) ⇒
33713375
* [~if_is_enum(type)](#module_Templating API_ static zcl helpers..if_is_enum) ⇒
33723376
* [~if_is_struct(type)](#module_Templating API_ static zcl helpers..if_is_struct) ⇒
3377+
* [~if_is_typedef(type)](#module_Templating API_ static zcl helpers..if_is_typedef) ⇒
33733378
* [~isClient(side)](#module_Templating API_ static zcl helpers..isClient) ⇒
33743379
* [~isServer(side)](#module_Templating API_ static zcl helpers..isServer) ⇒
33753380
* [~isStrEqual(str1, str2)](#module_Templating API_ static zcl helpers..isStrEqual) ⇒
@@ -3441,6 +3446,21 @@ enums belonging to a cluster.
34413446
| --- | --- |
34423447
| options | <code>\*</code> |
34433448

3449+
<a name="module_Templating API_ static zcl helpers..zcl_typedefs"></a>
3450+
3451+
### Templating API: static zcl helpers~zcl\_typedefs(options) ⇒
3452+
Block helper iterating over all typedefs.
3453+
If existing independently, it iterates over ALL the typedefs.
3454+
Within a context of a cluster, it iterates only over the
3455+
typedefs belonging to a cluster.
3456+
3457+
**Kind**: inner method of [<code>Templating API: static zcl helpers</code>](#module_Templating API_ static zcl helpers)
3458+
**Returns**: Promise of content.
3459+
3460+
| Param | Type |
3461+
| --- | --- |
3462+
| options | <code>\*</code> |
3463+
34443464
<a name="module_Templating API_ static zcl helpers..zcl_structs"></a>
34453465

34463466
### Templating API: static zcl helpers~zcl\_structs(options) ⇒
@@ -3524,6 +3544,36 @@ ignored), or a struct associated with the given cluster.
35243544
| clusterName |
35253545
| options |
35263546

3547+
<a name="module_Templating API_ static zcl helpers..zcl_typedef_by_typedef"></a>
3548+
3549+
### Templating API: static zcl helpers~zcl\_typedef\_by\_typedef(name, options) ⇒
3550+
Block helper for getting information for a typedef with a given name.
3551+
3552+
**Kind**: inner method of [<code>Templating API: static zcl helpers</code>](#module_Templating API_ static zcl helpers)
3553+
**Returns**: Promise of content.
3554+
3555+
| Param |
3556+
| --- |
3557+
| name |
3558+
| options |
3559+
3560+
<a name="module_Templating API_ static zcl helpers..zcl_typedef_by_typedef_and_cluster_name"></a>
3561+
3562+
### Templating API: static zcl helpers~zcl\_typedef\_by\_typedef\_and\_cluster\_name(name, clusterName, options) ⇒
3563+
Block helper for expanding a typedef. The typedef will be those that correspond to that
3564+
typedef name being used within the given cluster. That means the typedef name
3565+
must be either a global (in which case the cluster name is just
3566+
ignored), or a typedef associated with the given cluster.
3567+
3568+
**Kind**: inner method of [<code>Templating API: static zcl helpers</code>](#module_Templating API_ static zcl helpers)
3569+
**Returns**: Promise of content.
3570+
3571+
| Param |
3572+
| --- |
3573+
| name |
3574+
| clusterName |
3575+
| options |
3576+
35273577
<a name="module_Templating API_ static zcl helpers..zcl_device_types"></a>
35283578

35293579
### Templating API: static zcl helpers~zcl\_device\_types(options) ⇒
@@ -3897,6 +3947,12 @@ Helper that deals with the type of the argument.
38973947
| typeName | <code>\*</code> |
38983948
| options | <code>\*</code> |
38993949

3950+
<a name="module_Templating API_ static zcl helpers..asResolvedUnderlyingZclType"></a>
3951+
3952+
### Templating API: static zcl helpers~asResolvedUnderlyingZclType()
3953+
Helper that behaves like asUnderlyingZclType, but resolves typedefs.
3954+
3955+
**Kind**: inner method of [<code>Templating API: static zcl helpers</code>](#module_Templating API_ static zcl helpers)
39003956
<a name="module_Templating API_ static zcl helpers..asUnderlyingZclType"></a>
39013957

39023958
### Templating API: static zcl helpers~asUnderlyingZclType(typeName, options)
@@ -4122,6 +4178,25 @@ type is not struct
41224178
| --- |
41234179
| type |
41244180

4181+
<a name="module_Templating API_ static zcl helpers..if_is_typedef"></a>
4182+
4183+
### Templating API: static zcl helpers~if\_is\_typedef(type) ⇒
4184+
If helper that checks if a type is a typedef
4185+
4186+
* example:
4187+
{{#if_is_typedef type}}
4188+
type is typedef
4189+
{{else}}
4190+
type is not a typedef
4191+
{{/if_is_typedef}}
4192+
4193+
**Kind**: inner method of [<code>Templating API: static zcl helpers</code>](#module_Templating API_ static zcl helpers)
4194+
**Returns**: Promise of content.
4195+
4196+
| Param |
4197+
| --- |
4198+
| type |
4199+
41254200
<a name="module_Templating API_ static zcl helpers..isClient"></a>
41264201

41274202
### Templating API: static zcl helpers~isClient(side) ⇒

‎src-electron/db/db-mapping.js‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -425,6 +425,19 @@ exports.map = {
425425
}
426426
},
427427

428+
typedef: (x) => {
429+
if (x == null) return undefined
430+
return {
431+
id: x.TYPEDEF_ID,
432+
label: x.NAME,
433+
name: x.NAME,
434+
type: x.TYPE,
435+
typeId: x.TYPE_ID,
436+
caption: `Typedef, mapping to {@x.TYPE}`,
437+
typedefClusterCount: x.TYPEDEF_CLUSTER_COUNT
438+
}
439+
},
440+
428441
deviceType: (x) => {
429442
if (x == null) return undefined
430443
return {

‎src-electron/db/query-data-type.js‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -239,6 +239,11 @@ async function selectSizeFromType(db, packageIds, value) {
239239
dataType.discriminatorName.toLowerCase() == dbEnum.zclType.string
240240
) {
241241
return null
242+
} else if (
243+
dataType &&
244+
dataType.discriminatorName.toLowerCase() == dbEnum.zclType.typedef
245+
) {
246+
return await selectSizeFromType(db, packageIds, dataType.typeId)
242247
} else {
243248
return null
244249
}

‎src-electron/db/query-loader.js‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2321,6 +2321,58 @@ async function insertStructItems(db, packageIds, data) {
23212321
)
23222322
}
23232323

2324+
/**
2325+
* Insert all typedefs into the TypeDef Table.
2326+
*
2327+
* @param {*} db
2328+
* @param {*} packageIds
2329+
* @param {*} data
2330+
*/
2331+
async function insertTypedef(db, packageIds, data) {
2332+
return dbApi.dbMultiInsert(
2333+
db,
2334+
`
2335+
INSERT INTO
2336+
TYPEDEF (TYPEDEF_ID, DATA_TYPE_REF)
2337+
VALUES (
2338+
(SELECT
2339+
CASE
2340+
WHEN
2341+
(${SELECT_CLUSTER_SPECIFIC_DATA_TYPE} AND PACKAGE_REF IN (${dbApi.toInClause(
2342+
packageIds
2343+
)}))
2344+
IS
2345+
NULL
2346+
THEN
2347+
(${SELECT_GENERIC_DATA_TYPE} AND PACKAGE_REF IN (${dbApi.toInClause(
2348+
packageIds
2349+
)}))
2350+
ELSE
2351+
(${SELECT_CLUSTER_SPECIFIC_DATA_TYPE} AND PACKAGE_REF IN (${dbApi.toInClause(
2352+
packageIds
2353+
)}))
2354+
END AS DATA_TYPE_ID),
2355+
(SELECT
2356+
DATA_TYPE_ID
2357+
FROM
2358+
DATA_TYPE
2359+
WHERE
2360+
DATA_TYPE.PACKAGE_REF IN (${dbApi.toInClause(packageIds)})
2361+
AND DATA_TYPE.NAME = ?))`,
2362+
data.map((at) => [
2363+
at.name,
2364+
at.discriminator_ref,
2365+
at.cluster_code ? parseInt(at.cluster_code[0].$.code, 16) : null,
2366+
at.name,
2367+
at.discriminator_ref,
2368+
at.name,
2369+
at.discriminator_ref,
2370+
at.cluster_code ? parseInt(at.cluster_code[0].$.code, 16) : null,
2371+
at.type
2372+
])
2373+
)
2374+
}
2375+
23242376
exports.insertGlobals = insertGlobals
23252377
exports.insertClusterExtensions = insertClusterExtensions
23262378
exports.insertClusters = insertClusters
@@ -2346,6 +2398,7 @@ exports.insertBitmap = insertBitmap
23462398
exports.insertBitmapFields = insertBitmapFields
23472399
exports.insertStruct = insertStruct
23482400
exports.insertStructItems = insertStructItems
2401+
exports.insertTypedef = insertTypedef
23492402
exports.updateDataTypeClusterReferences = updateDataTypeClusterReferences
23502403
exports.insertAttributeMappings = insertAttributeMappings
23512404
exports.insertEndpointComposition = insertEndpointComposition

0 commit comments

Comments
 (0)