This is an automated email from the ASF dual-hosted git repository.
hutcheb pushed a commit to branch develop
in repository https://gitbox.apache.org/repos/asf/plc4x.git
The following commit(s) were added to refs/heads/develop by this push:
new 6f6867c19b fix: Update mspec documentation to include the state,
batchSet, constants fields and types
6f6867c19b is described below
commit 6f6867c19b210362723c1ee7760fbc58ec319c78
Author: hutcheb <[email protected]>
AuthorDate: Sat Oct 25 09:58:23 2025 +0800
fix: Update mspec documentation to include the state, batchSet, constants
fields and types
---
.../modules/developers/pages/building.adoc | 1 +
.../developers/pages/code-gen/protocol/mspec.adoc | 43 +++++++++++++++++++++-
2 files changed, 42 insertions(+), 2 deletions(-)
diff --git a/website/asciidoc/modules/developers/pages/building.adoc
b/website/asciidoc/modules/developers/pages/building.adoc
index c2989fce7d..26dc42b944 100644
--- a/website/asciidoc/modules/developers/pages/building.adoc
+++ b/website/asciidoc/modules/developers/pages/building.adoc
@@ -68,6 +68,7 @@ The following profiles are available:
- `with-go`: Builds all Go related modules
- `with-java`: Builds all Java related modules
- `with-python`: Builds all Python related modules
+- `update-code-generation`: Generates the generated code from the mspec
definitions
WARNING: As these profiles typically require some preparation and setup on
your development machine, please read the link:preparing/index.html[Preparing
your Computer] guide for a detailed description on this.
diff --git
a/website/asciidoc/modules/developers/pages/code-gen/protocol/mspec.adoc
b/website/asciidoc/modules/developers/pages/code-gen/protocol/mspec.adoc
index 303ea56cee..7ba4f2b2a5 100644
--- a/website/asciidoc/modules/developers/pages/code-gen/protocol/mspec.adoc
+++ b/website/asciidoc/modules/developers/pages/code-gen/protocol/mspec.adoc
@@ -27,7 +27,7 @@ After we had an initial format that seemed to do the trick,
we then stated creat
It's a text-based format.
-At the root level of these specs are a set of `type`, `discriminatedType`,
`dataIo` and `enum` blocks.
+At the root level of these specs are a set of `type`, `discriminatedType`,
`dataIo`, `enum` and 'constants' blocks.
`type` elements are objects who`s content and structure is independent of the
input.
@@ -75,6 +75,13 @@ For example part of the spec for the S7 format looks like
this:
]
....
+A constants type allows you to define constants for the protocol.
+....
+[constants
+ [const uint 16 adsDiscoveryUdpDefaultPort 48899]
+]
+....
+
A type`s start is declared by an opening square bracket `[` followed by the
`type` or `discriminatedType` keyword, which is directly followed by a name.
A Type definition is ended with a closing square bracket `]`.
@@ -85,6 +92,7 @@ The list of available field types are:
- abstract: used in the parent type declaration do declare a field that has to
be defined with the identical type in all subtypes (reserved for
`discriminatedType`).
- array: array of simple or complex typed objects.
- assert: generally similar to `constant` fields, however do they throw
`AssertionExceptions` instead of hard `ParseExceptions`. They are used in
combination with optional fields.
+- batchSet: this is a psuedo field that allows you to apply additional
attributes for a group of fields
- checksum: used for calculating and verifying checksum values.
- const: expects a given value and causes a hard exception if the value
doesn't match.
- discriminator: special type of simple typed field which is used to determine
the concrete type of object (reserved for `discriminatedType`).
@@ -97,6 +105,7 @@ The list of available field types are:
- peek: field that tries to parse a given structure without actually consuming
the bytes.
- reserved: expects a given value, but only warns if condition is not meet.
- simple: simple or complex typed object.
+- state: Allows you to assign a parameter as a stateful variable in a class.
- typeSwitch: not a real field, but indicates the existence of subtypes, which
are declared inline (reserved for `discriminatedType`).
- unknown: field used to declare parts of a message that still has to be
defined. Generally used when reverse-engineering a protocol. Messages with
`unknown` fields can only be parsed and not serialized.
- validation: this field is not actually a real field, it's more a condition
that is checked during parsing and if the check fails, it throws a validation
exception, wich is handled by
@@ -187,6 +196,20 @@ See also:
- validation field: Similar to an `assert` field, however no parsing is done,
and instead simply a condition is checked.
- optional field: `optional` fields are aware of the types of parser errors
produced by `assert` and `validation` fields
+== batchSet Field
+
+A batch set field allows you to define or modify attributes for a group of
fields.
+
+ [batchSet byteOrder='integerEncoding == IntegerEncoding.BIG_ENDIAN ?
BIG_ENDIAN : LITTLE_ENDIAN'
+
+ [simple DceRpc_ObjectUuid objectUuid
]
+
+ [simple DceRpc_InterfaceUuid interfaceUuid
]
+
+ [simple DceRpc_ActivityUuid activityUuid
]
+ ]
+
+
=== checksum Field
A checksum field can only operate on simple types.
@@ -484,4 +507,20 @@ Unsigned integers for example use 2s-complement notation,
floating point values
However, in some cases an alternate encoding needs to be used. Especially when
dealing with Strings, different encodings, such as ASCII, UTF-16 and many more,
can be used. But also for numeric values, different encodings might be used.
For example does KNX use a 16bit floating point encoding, which is not standard
or in S7 drivers a special encoding was used to encode numeric values so they
represent the number in hex format.
-An `encoding` attribute can be used to select a non-default encoding.
\ No newline at end of file
+An `encoding` attribute can be used to select a non-default encoding.
+
+== Referencing parent class name of discriminated types
+
+For discriminated type it is convient sometimes to not have to repeat the
parent class name for each case.
+Here you can use the * reference at the start of each case name
+
+ [discriminatedType SuperImportantClass
+ [simple uint 8 testNumber]
+ [typeSwitch testNumber
+ ['0x08' *Status
+ [simple uint 8 testNewNumber]
+ ]
+ ]
+ ]
+
+Here the child class will inherit the class name SuperImportantClassStatus
