mirror of
https://github.com/eclipse-openvehicle-api/openvehicle-api.git
synced 2026-04-18 18:48:16 +00:00
387 lines
19 KiB
Plaintext
387 lines
19 KiB
Plaintext
/********************************************************************************
|
|
* Copyright (c) 2025-2026 ZF Friedrichshafen AG
|
|
*
|
|
* This program and the accompanying materials are made available under the
|
|
* terms of the Apache License Version 2.0 which is available at
|
|
* https://www.apache.org/licenses/LICENSE-2.0
|
|
*
|
|
* SPDX-License-Identifier: Apache-2.0
|
|
*
|
|
* Contributors:
|
|
* Erik Verhoeven - initial API and implementation
|
|
********************************************************************************/
|
|
|
|
#include "core.idl"
|
|
|
|
/**
|
|
* @brief Software Defined Vehicle framework.
|
|
*/
|
|
module sdv
|
|
{
|
|
/**
|
|
* @brief TOML interface.
|
|
*/
|
|
module toml
|
|
{
|
|
/**
|
|
* @brief TOML parse exception.
|
|
*/
|
|
exception XTOMLParseException : XSysExcept
|
|
{
|
|
/** Description */
|
|
const char _description[] = "TOML parse exception.";
|
|
|
|
u8string ssMessage; ///< Message indicating the cause of the exception.
|
|
};
|
|
|
|
/**
|
|
* @brief Collection of possible data in parse tree node
|
|
*/
|
|
enum ENodeType : uint32
|
|
{
|
|
node_table, ///< Table
|
|
node_array, ///< Array
|
|
node_integer, ///< Integer
|
|
node_floating_point, ///< Floating point
|
|
node_boolean, ///< Boolean
|
|
node_string, ///< String
|
|
node_invalid ///< Invalid content
|
|
};
|
|
|
|
/**
|
|
* @brief The indicator of an invalid position used in various functions using indices.
|
|
*/
|
|
const uint32 npos = 0xFFFFFFFF;
|
|
|
|
/**
|
|
* @brief Node information interface
|
|
*/
|
|
interface INodeInfo
|
|
{
|
|
/**
|
|
* @brief Get the node name (no conversion to a literal or quoted key is made).
|
|
* @return String containing the name of the node.
|
|
*/
|
|
u8string GetName() const;
|
|
|
|
/**
|
|
* @brief Get the node path following the key rules for bar, literal and quoted keys.
|
|
* @param[in] bResolveArrays When set, include array indices in the path. The path returned without array indices is
|
|
* identical to the code in the TOML file. The path returned with array indices is identical to the direct access of
|
|
* nodes within the parser.
|
|
* @return String containing the path of the node.
|
|
*/
|
|
u8string GetPath(in boolean bResolveArrays) const;
|
|
|
|
/**
|
|
* @brief Get the node type.
|
|
* @return Type of the node.
|
|
*/
|
|
ENodeType GetType() const;
|
|
|
|
/**
|
|
* @brief The node value.
|
|
* @return For boolean, integer, floating point and strings, the function returns a value. Otherwise the function
|
|
* returns empty.
|
|
*/
|
|
any GetValue() const;
|
|
|
|
/**
|
|
* @brief Get the index of this node within the parent collection.
|
|
* @return The index of the node within the parent collection node or npos when no parent is available.
|
|
*/
|
|
uint32 GetIndex() const;
|
|
|
|
/**
|
|
* @brief Get the parent collection node.
|
|
* @return Returns the parent collection node or NULL when there is no parent collection node.
|
|
*/
|
|
IInterfaceAccess GetParent() const;
|
|
|
|
/**
|
|
* @brief Return the TOML string belonging to this node including all potential child nodes and comments.
|
|
* @return The TOML string.
|
|
*/
|
|
u8string GetTOML() const;
|
|
|
|
/**
|
|
* @brief Node comment type.
|
|
*/
|
|
enum ECommentType
|
|
{
|
|
comment_before = 0, ///< The comment before the node. This will insert a newline and the comment
|
|
///< text preceded by the '#' character.
|
|
comment_behind = 1, ///< The comment behind the node. This will align the comment to te next tab
|
|
///< stop and precedes the comment with the '#' character.
|
|
out_of_scope_comment_before = 2, ///< An independent comment before the node. This comment is not part of the
|
|
///< node and is separated by an extra newline.
|
|
out_of_scope_comment_behind = 3, ///< An independent comment behind the node. This comment is not part of the
|
|
///< node and is separated by an extra newline.
|
|
};
|
|
|
|
/**
|
|
* @brief Set or replace a comment for the node.
|
|
* @details Set the comment text for the node. If a comment is provided as text (normal behavior), the comment text will
|
|
* be formatted automatically when generating the TOML text. If the comment text should not contain the comment
|
|
* character '#' before the comment text.
|
|
* Comments inserted before the node will be inserted on the line before the node unless the comment is provided in raw
|
|
* format and is ended with a line-break and optionally whitespace. Comment inserted behind the node will be inserted on
|
|
* the same line as the node.
|
|
* Comments provided as text is automatically wrapped to 132 characters if possible. Line-breaks in the text will cause
|
|
* a new comment line to start.
|
|
* @param[in] eType The comment type to set the comment text for.
|
|
* @param[in] ssComment String containing the comment text to set.
|
|
*/
|
|
void SetComment(in ECommentType eType, in u8string ssComment);
|
|
|
|
/**
|
|
* Get the current comment for the node.
|
|
* @param[in] eType The comment type to get the comment text of.
|
|
* @return String with the comment text or an empty string if no comment is available.
|
|
*/
|
|
u8string GetComment(in ECommentType eType);
|
|
|
|
/**
|
|
* @brief Format the node automatically. This will remove the whitespace between the elements within the node. Comments
|
|
* will not be changed.
|
|
*/
|
|
void AutomaticFormat();
|
|
|
|
/**
|
|
* @brief Is the node inline?
|
|
* @return Returns whether the node is defined as inline node.
|
|
*/
|
|
boolean IsInline() const;
|
|
|
|
/**
|
|
* @brief Is the node defined as standard node?
|
|
* @return Returns whether the node is defined as standard node.
|
|
*/
|
|
boolean IsStandard() const;
|
|
};
|
|
|
|
/**
|
|
* @brief Update the current node.
|
|
* @remarks The root node cannot be updated.
|
|
*/
|
|
interface INodeUpdate
|
|
{
|
|
/**
|
|
* @brief Change the key name of the node (if the node is not a value node of an array).
|
|
* @param[in] ssNewName The name to assign to the node. The name must adhere to the key names defined by the TOML
|
|
* specification. Defining the key multiple times is not allowed. Quotation of key names is done automatically; the
|
|
* parser decides itself whether the key is bare-key, a literal key or a quoted key.
|
|
* @return Returns whether the name change was successful.
|
|
*/
|
|
boolean ChangeName(in u8string ssNewName);
|
|
|
|
/**
|
|
* @brief Change the value of the node.
|
|
* @remarks Only valid for value nodes. Changing the value type is not supported.
|
|
* @param[in] anyNewValue The value of the node, being either an integer, floating point number, boolean value or a
|
|
* string. Conversion is automatically done to int64, double float, bool or u8string.
|
|
* @return Returns whether the value change was successful.
|
|
*/
|
|
boolean ChangeValue(in any anyNewValue);
|
|
|
|
/**
|
|
* @brief Move up the node in the collection.
|
|
* @remarks External tables or table arrays cannot be moved before value nodes.
|
|
* @remarks Moving if the node is the first node is not possible.
|
|
* @return Returns whether the move was successful.
|
|
*/
|
|
boolean MoveUp();
|
|
|
|
/**
|
|
* @brief Move down the node in the collection.
|
|
* @remarks Value nodes cannot be moved behind external tables or table arrays.
|
|
* @remarks Moving if the node is the last node is not possible.
|
|
* @return Returns whether the move was successful.
|
|
*/
|
|
boolean MoveDown();
|
|
|
|
/**
|
|
* @brief Delete the current node.
|
|
* @attention A successful deletion will cause all interfaces to the current node to become inoperable.
|
|
* @return Returns whether the deletion was successful.
|
|
*/
|
|
boolean DeleteNode();
|
|
};
|
|
|
|
/**
|
|
* @brief Interface allowing access to table and array nodes.
|
|
*/
|
|
interface INodeCollection
|
|
{
|
|
/**
|
|
* @brief Returns the amount of nodes.
|
|
* @return The amount of nodes.
|
|
*/
|
|
uint32 GetCount() const;
|
|
|
|
/**
|
|
* @brief Get the node.
|
|
* @param[in] uiIndex Index of the node to get.
|
|
* @return Interface to the node object.
|
|
*/
|
|
IInterfaceAccess GetNode(in uint32 uiIndex) const;
|
|
|
|
/**
|
|
* @brief Searches a node by its key in the parse tree
|
|
* @details Elements of tables can be accessed and traversed by using '.' to separated the parent name from child
|
|
* name. E.g. 'parent.child' would access the 'child' element of the 'parent' table. Elements of arrays can be
|
|
* accessed and traversed by using the index number in brackets. E.g. 'array[3]' would access the fourth element of
|
|
* the array 'array'. These access conventions can also be chained like 'table.array[2][1].subtable.integerElement'.
|
|
* @attention Array indexing starts with 0!
|
|
* @param[in] ssPath The path of the Node to searched for.
|
|
* @return Returns an interface the requested node if available.
|
|
*/
|
|
IInterfaceAccess GetNodeDirect(in u8string ssPath) const;
|
|
};
|
|
|
|
/**
|
|
* @brief Convert between inline and standard definitions.
|
|
*/
|
|
interface INodeCollectionConvert
|
|
{
|
|
/**
|
|
* @brief Can the node convert to an inline definition?
|
|
* @return Returns whether the conversion to inline is possible. Returns 'true' when the node is already inline.
|
|
*/
|
|
boolean CanMakeInline() const;
|
|
|
|
/**
|
|
* @brief Convert the node to an inline node.
|
|
* @return Returns whether the conversion was successful. Returns 'true' when the node was already inline.
|
|
*/
|
|
boolean MakeInline();
|
|
|
|
/**
|
|
* @brief Can the node convert to a standard definition?
|
|
* @return Returns whether the conversion to standard is possible. Returns 'true' when the node is already defined as
|
|
* standard node.
|
|
*/
|
|
boolean CanMakeStandard() const;
|
|
|
|
/**
|
|
* @brief Convert the node to a standard node.
|
|
* @return Returns whether the conversion was successful. Returns 'true' when the node was already defined as standard
|
|
* node.
|
|
*/
|
|
boolean MakeStandard();
|
|
};
|
|
|
|
/**
|
|
* @brief Extend the collection node with values, arrays and tables.
|
|
*/
|
|
interface INodeCollectionInsert
|
|
{
|
|
/**
|
|
* @brief Insert a value into the collection at the location before the supplied index.
|
|
* @param[in] uiIndex The insertion location to insert the node before. Can be npos or any value larger than the
|
|
* collection count to insert the node at the end of the collection. Value nodes cannot be inserted behind external
|
|
* tables and table arrays. If the index is referencing a position behind an external table or a table array, the index
|
|
* is automatically corrected.
|
|
* @param[in] ssName Name of the node to insert. Will be ignored for an array collection. The name must adhere to the
|
|
* key names defined by the TOML specification. Defining the key multiple times is not allowed. Quotation of key names
|
|
* is done automatically; the parser decides itself whether the key is bare-key, a literal key or a quoted key.
|
|
* @param[in] anyValue The value of the node, being either an integer, floating point number, boolean value or a string.
|
|
* Conversion is automatically done to int64, double float, bool or u8string.
|
|
* @return On success the interface to the newly inserted node is returned or NULL otherwise.
|
|
*/
|
|
IInterfaceAccess InsertValue(in uint32 uiIndex, in u8string ssName, in any anyValue);
|
|
|
|
/**
|
|
* @brief Insert an array into the collection at the location before the supplied index.
|
|
* @param[in] uiIndex The insertion location to insert the node before. Can be npos or any value larger than the
|
|
* collection count to insert the node at the end of the collection. Array nodes cannot be inserted behind external
|
|
* tables and table arrays. If the index is referencing a position behind an external table or a table array, the index
|
|
* is automatically corrected.
|
|
* @param[in] ssName Name of the array node to insert. Will be ignored if the current node is also an array collection.
|
|
* The name must adhere to the key names defined by the TOML specification. Defining the key multiple times is not
|
|
* allowed. Quotation of key names is done automatically; the parser decides itself whether the key is bare-key, a
|
|
* literal key or a quoted key.
|
|
* @return On success the interface to the newly inserted node is returned or NULL otherwise.
|
|
*/
|
|
IInterfaceAccess InsertArray(in uint32 uiIndex, in u8string ssName);
|
|
|
|
/**
|
|
* @brief Insertion preference for tables and table arrays, being standard or inline.
|
|
*/
|
|
enum EInsertPreference
|
|
{
|
|
prefer_standard = 0, ///< When the parent node is not inline, the node will be inserted as standard node.
|
|
prefer_inline = 1, ///< The node will be inserted as inline node.
|
|
};
|
|
|
|
/**
|
|
* @brief Insert a table into the collection at the location before the supplied index.
|
|
* @param[in] uiIndex The insertion location to insert the node before. Can be npos or any value larger than the
|
|
* collection count to insert the node at the end of the collection. Table nodes cannot be inserted before value nodes
|
|
* or arrays. If the index is referencing a position before a value node or an array, the index is automatically
|
|
* corrected.
|
|
* @param[in] ssName Name of the table node to insert. Will be ignored if the parent node is an array collection.
|
|
* The name must adhere to the key names defined by the TOML specification. Defining the key multiple times is not
|
|
* allowed. Quotation of key names is done automatically; the parser decides itself whether the key is bare-key, a
|
|
* literal key or a quoted key.
|
|
* @param[in] ePreference The preferred form of the node to be inserted.
|
|
* @return On success the interface to the newly inserted node is returned or NULL otherwise.
|
|
*/
|
|
IInterfaceAccess InsertTable(in uint32 uiIndex, in u8string ssName, in EInsertPreference ePreference);
|
|
|
|
/**
|
|
* @brief Insert a table array into the collection at the location before the supplied index.
|
|
* @param[in] uiIndex The insertion location to insert the node before. Can be npos or any value larger than the
|
|
* collection count to insert the node at the end of the collection. Table array nodes cannot be inserted before value
|
|
* nodes or arrays. If the index is referencing a position before a value node or an array, the index is automatically
|
|
* corrected.
|
|
* @param[in] ssName Name of the array node to insert. Will be ignored if the parent node is also an array collection.
|
|
* The name must adhere to the key names defined by the TOML specification. Defining the key multiple times is not
|
|
* allowed. Quotation of key names is done automatically; the parser decides itself whether the key is bare-key, a
|
|
* literal key or a quoted key.
|
|
* @param[in] ePreference The preferred form of the node to be inserted.
|
|
* @return On success the interface to the newly inserted node is returned or NULL otherwise.
|
|
*/
|
|
IInterfaceAccess InsertTableArray(in uint32 uiIndex, in u8string ssName, in EInsertPreference ePreference);
|
|
|
|
/**
|
|
* @brief The result of the TOML string to insert.
|
|
*/
|
|
enum EInsertResult : uint32
|
|
{
|
|
insert_fail, ///< The TOML string was invalid or didn't fit the collection node it was to be inserted.
|
|
insert_partly_success, ///< Part, but not all nodes could be inserted (duplicate nodes are not inserted).
|
|
insert_success, ///< All nodes could be inserted or the TOML didn't contain any nodes.
|
|
};
|
|
|
|
/**
|
|
* @brief Insert a TOML string as a child of the current collection node. If the collection is a table, the TOML string
|
|
* should contain values and inline/external/array-table nodes with names. If the collection is an array, the TOML
|
|
* string should contain and inline table nodes without names.
|
|
* @attention Even though the TOML might be defining the node(s) in standard form, if the parent node is an inline node,
|
|
* the node will be inserted as inline node.
|
|
* @param[in] uiIndex The insertion location to insert the node before. Can be npos or any value larger than the
|
|
* collection count to insert the node at the end of the collection. Table array nodes cannot be inserted before value
|
|
* nodes or arrays. If the index is referencing a position before a value node or an array, the index is automatically
|
|
* corrected.
|
|
* @param[in] ssTOML The TOML string to insert. This string can hold one or more nodes that should be inserted.
|
|
* @param[in] bRollbackOnFailure If only part of the nodes could be inserted, no node will be inserted.
|
|
* @return The result of the insertion.
|
|
*/
|
|
EInsertResult InsertTOML(in uint32 uiIndex, in u8string ssTOML, in boolean bRollbackOnFailure);
|
|
};
|
|
|
|
/**
|
|
* @brief TOML parser interface.
|
|
*/
|
|
interface ITOMLParser
|
|
{
|
|
/**
|
|
* @brief Process the configuration from the supplied content string.
|
|
* @param[in] ssContent Configuration string.
|
|
* @return Returns 'true' when the configuration could be read successfully, false when not.
|
|
*/
|
|
boolean Process(in u8string ssContent) raises(XTOMLParseException);
|
|
};
|
|
};
|
|
}; |