diff options
Diffstat (limited to 'src/ivicore/doc/src/ivigenerator/idl-syntax.qdoc')
| -rw-r--r-- | src/ivicore/doc/src/ivigenerator/idl-syntax.qdoc | 318 |
1 files changed, 318 insertions, 0 deletions
diff --git a/src/ivicore/doc/src/ivigenerator/idl-syntax.qdoc b/src/ivicore/doc/src/ivigenerator/idl-syntax.qdoc new file mode 100644 index 0000000..f44eee1 --- /dev/null +++ b/src/ivicore/doc/src/ivigenerator/idl-syntax.qdoc @@ -0,0 +1,318 @@ +/**************************************************************************** +** +** Copyright (C) 2018 Pelagicore AG +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the documentation of the QtIvi module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL-QTAS$ +** Commercial License Usage +** Licensees holding valid commercial Qt Automotive Suite licenses may use +** this file in accordance with the commercial license agreement provided +** with the Software or, alternatively, in accordance with the terms +** contained in a written agreement between you and The Qt Company. For +** licensing terms and conditions see https://www.qt.io/terms-conditions. +** For further information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ +/* + NOTE: Some content in this file was copied from the QFace Documentation +*/ +/*! +\page idl-syntax.html +\title QFace IDL syntax +\nextpage Jinja template syntax +\keyword IDL + +This page explains the basic usage of the QFace IDL. A more detailed description of the library +can be found on its \l {https://pelagicore.github.io/qface/}{page} + +QFace (Qt interface language) is an Interface Description Languge (IDL). While it is primarily +designed to define an interface between Qt, QML and C++, it is intended to be flexible enough also +to be used in other contexts. + + +\section1 The IDL + +The IDL uses common API concepts such as modules, interfaces, properties, structs and enums/flags. +Additionally it knows about lists and \l {Model/View Programming}{models}. +A list is an array of primitive or complex types. A model is an indicator for large data sets +which are typical used via a defined API (e.g. pagination). + +\code +module org.example 1.0 + +interface Echo { + string message; + void echo(string message); + signal broadcast(string message); + Status status; +} + +enum Status { + Null, Loading, Ready, Error +} +\endcode + +The data types provided by QFace can be divided into primitive and complex types: + +\b {Primitive Types} +\list + \li bool + \li int + \li real + \li string + \li var +\endlist + +\b {Complex Types} +\list + \li Interface + \li Struct + \li Enum + \li Flag + \li Array + \li Model +\endlist + +The language as such does not provide any support for maps or dictionaries. The reason for not +providing a map container type is that keys in dictionaries requires a hash which can not always +be guaranteed to be available in complex types. + +\section1 Grammar +The grammar of QFace is well defined and is based on the concepts of modules as a larger +collection of information. + +A module can have several interfaces, structs and/or enums/flags. + +\code +module <module> <version> +import <module> <version> + +interface <Identifier> { + [readonly] <type> <identifier> + <type> <operation>(<parameter>*) + signal <signal>(<parameter>*) +} + +struct <Identifier> { + <type> <identifier>; +} + +enum <Identifier> { + <name> = <value>, +} + +flag <Identifier> { + <name> = <value>, +} +\endcode + +A QFace document always describes one module. Each document can contain one or more interfaces, +structs, flags or enums. Each document can import other modules using the import statement. + +\section1 Module + +A module is identified by its name. The name should normally be a URI where all parts are +lowercase (e.g. \e {entertainment.tuner}). A module may import other modules with the primary +purpose being to ensure that dependencies are declared inside the QFace file. + +\code +// org.example.qface +module org.example 1.0 + +import org.common 1.0 +\endcode + +\section1 Interface + +An interface is a collection of properties, operation and signals. Properties carry data, whereas +the operations normally modify the data. Signals are used to notify the user of changes. + +\code +interface WeatherStation { + real temperature; + void reset(); + signal error(string message); +} +\endcode + +\section1 Struct + +The struct is supposed to serve as a container to transport structured data. It supports neither +properties nor operations. + +\section1 Property + +Interfaces and structures data are carried by properties: syntax elements allowing to describe +some attributes of the entity. A property can be of any type, known to IDL. It can be marked as \e +{readonly}, in which case this attribute of the interface is not supposed to be written to from +the outside code. It's up to the generator to enforce this constraint. + +\section1 Enum/Flag +Enums and flags are the concepts known from many popular programming languages (C++,Java,etc). +They differ only in what values they can take: enums are allowed to take only a single value, +whereas flags can be an OR-ed combination of multiple values. + +\section1 Types + +Types are either local and can be referenced simply by their name, or they are from an external +module in which case they need to be referenced with the fully qualified name (module + '.' + +name). A type can be an interface, struct, enum or flag. + +A module consists of either one or more interfaces, structs and enums/flags. They can come in any +number or combination. The interface is the only type which can contain operations and signals. +A struct is merely a container to transport structured data. Enum and flags allows the user to +encode information used inside the struct or interface as datatype. + +The QFace library does not allow to extend interfaces. It is by design kept simple. + +Below is an example of a QFace file. + +\code +module entertainment.tuner 1.0; + +import common 1.0 + +interface Tuner { + // property currentStation + readonly Station currentStation; + // operation nextStation + void nextStation(); + // operation previousStation + void previousStation(); + // operation updateCurrentStation + void updateCurrentStation(int stationId); + + list<int> primitiveList; + list<Station> complexList; + model<int> primitiveModel; + model<Station> complexModel; +} + +\endcode + + +\section1 Annotations +\target annotations_reference + +Annotations is a way to add meta information to your interface definition. It is available to each +symbol in the interface. + +Annotations allows an interface author to extend the existing interface with additional meta +information, called tags, aka annotations. One or several annotations can precede a module, +interface, struct or enum. They are also allowed before an operation, property or signal. +Everywhere where a documentation comment is allowed you can also add annotations. + +An annotation looks like this: + +\code +@service: {port: 12345} +interface Tuner { +} +\endcode + +An in code annotation precedes a symbol and it starts with an @ sign. A symbol can have more than +one one annotation line. Each line should be one individual annotation. The content is YAML +content. All @ signs preceding a symbol are collected and then evaluated using a YAML parser. + +For larger annotations one can use the external annotation document feature. + +\code +@singleton: yes +@data: [1,2,3] +@config: { values: [LEFT, RIGHT, TOP] } +\endcode + +This will be result into a YAML content of + +\code +singleton: yes +data: [1,2,3] +config: { values: [LEFT, RIGHT, TOP] } +\endcode + +And the result as Python object would be + +\code +{ + "data": [ 1, 2, 3 ], + "singleton": true, + "config": { + "values": [ "LEFT", "RIGHT", "TOP" ] + } +} +\endcode + +\section1 Annotation Documents + +QFace allows also to specify these annotations in external documents using the YAML syntax. For +this you need to create a document with the same name as the QFace document but with the extension +.yaml. It should have roughly the following format + +\code +com.pelagicore.ivi.Tuner: + service: + port: 12345 +\endcode + +On the root level should be a fully qualified name of a symbol. The symbol will be looked up and +the following annotation information merged with the existing annotations from the QFace document. + +\section1 Merging Annotations + +The external annotations will be merged on top of the embedded annotations on per symbol base. +Dictionaries will be merged. If a merge can not be done then the external document based +annotations will override the embedded annotations. + +The annotation are available later when navigating the domain model. + +\code +{% if "service" in interface.tags %} +interface {{interface}} is served on port: {{interface.tags.service.port}} +{% else %} +interface {{interface}} is not served +{% endif %} +\endcode + +\note +QFace does not specify specific annotations, but defines just the annotation format. The set of +annotations supported must be defined and documented by the generator. + +\section1 Domain Model + +As a result of parsing the IDL document, a domain model object must be created. The domain model +resembles the structure of our system as objects. It is build by the parser and serves as the +input into the generator. + +The IDL is converted into an in memory domain model (see qface/idl/domain.py) + +\code +- System + - Module + - Import + - Interface + - Property + - Operation + - Event + - Enum + - Flag + - Struct + - Property +\endcode + +The domain model is the base for the code generation. You traverse the domain tree and trigger +your own code generation. + +Detailed description of QFace library API is found on the library \l +{http://qface.readthedocs.io/en/latest/api.html} {page} +*/ |