path: root/src/ivicore/doc/src/ivigenerator/idl-syntax.qdoc

/****************************************************************************
**
** Copyright (C) 2021 The Qt Company Ltd.
** Copyright (C) 2019 Luxoft Sweden AB
** Copyright (C) 2018 Pelagicore AG
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt 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 topic explains how to use the QFace IDL. A complete description of the library is available
at \l {https://pelagicore.github.io/qface/}.

QFace (Qt Interface Language) is an Interface Description Languge (IDL). While it's primarily
designed to define an interface between Qt, QML, and C++, it is flexible enough to be used in other
contexts.

\section1 The IDL

The IDL uses common API concepts such as modules, interfaces, properties, structs, enums, or flags.
Additionally, the IDL knows about lists and \l {Model/View Programming}{models}:

\list
    \li list - an array of primitive or complex types
    \li model - an container for large data sets, typically used via a defined API
\endlist

\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. QFace doesn't provide
a map container type because keys in dictionaries require a hash, which isn't always 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, enums, or 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, enums, or flags. Each document can import other modules using the import statement.

\note There are some limitations with the Qt Ivi generator that parses the QFace IDL file.
For more information, see \l{known-limitations}{Known Limitations}.

\section1 Module

A module consists of one or more interfaces, structs, enums, or flags; in any combination. A module
is identified by its name. This name should be a URI, such as, \e {entertainment.tuner}.

\section1 Interface

An interface is a collection of properties, operations, and signals. Properties carry data, while
operations modify data. Signals are used to notify the user about changes that have taken place.
The interface is the only type that can contain operations and signals.

\code
interface WeatherStation {
    real temperature;
    void reset();
    signal error(string message);
}
\endcode

The QFace library does not allow for interfaces to be extended; this is by design.

\section1 Struct

The struct serves as a container to transport structured data. Unlike an interface, a struct
doesn't support operations and signals.

\section1 Property

Properties carry data about interfaces and structures: syntax elements allow you to describe some
attributes of the data. A property can be of any type known to the IDL. It can be marked as
\c readonly, in which case this attribute of the interface is not supposed to be written to from
code outside. But it's up to the generator to enforce this constraint.

\section1 Enum or Flag

Enum and flags allows you to encode information used inside the struct or interface as data types.
Enums and flags are common concepts in many popular programming languages. But in the IDL, enums
are allowed to take single value only, whereas flags can take a combination of multiple values
that are combined with the bitwise OR operator.

\section1 Type

A type can be an interface, struct, enum, or flag. Types are either local or external. Local types
can be referenced by their name. External types are from an external module, and they need to be
referenced with their fully qualified name, \c module.<name>.

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

\note There are some limitations with the Qt Ivi generator that parses the QFace IDL file.
For more information, see \l{known-limitations}{Known Limitations}.

\section1 Annotation
\target annotations_reference

Annotations are a way to add meta information to your interface definition, such as tags.
They are available to each symbol in the interface.

A module, interface, struct, or enum, can be preceded by one or several annotations. You can also
use annotations before an operation, property, or signal. Ultimately, you can use annotations
anywhere documentation comments are allowed.

An annotation is written as follows:

\code
@service: {port: 12345}
interface Tuner {
}
\endcode

An in-code annotation precedes a symbol and starts with the \c @ sign. A symbol can have more
than one annotation line, with each line having one individual annotation. The content is in
YAML format. All @ signs preceding a symbol are collected and then evaluated using a YAML parser.

For larger annotations, you can use the external annotation document feature.

\code
@singleton: yes
@data: [1,2,3]
@config: { values: [LEFT, RIGHT, TOP] }
\endcode

This results in the following YAML content:

\code
singleton: yes
data: [1,2,3]
config: { values: [LEFT, RIGHT, TOP] }
\endcode

The result, as a Python object, would be:

\code
{
  "data": [ 1, 2, 3 ],
  "singleton": true,
  "config": {
    "values": [ "LEFT", "RIGHT", "TOP" ]
  }
}
\endcode

\section1 Annotation Documents

QFace allows you to also 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 wth a \c .yaml
extension.

Your document should resemble the following:

\code
com.pelagicore.ivi.Tuner:
    service:
      port: 12345
\endcode

The root level should contain a symbol's fully qualified name. This symbol is looked up and the
accompanying annotation information is then merged with any existing annotations from the QFace
document.

\target merge-annotations
\section1 Merge Annotations

The external annotations are merged on top of the embedded annotations, per symbol; dictionaries
are also merged. If a merge can't be done, then the external document based annotations will
always override the embedded annotations.

When you navigate the domain model, the external annotations are placed in a later portion.

\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 the annotation format only. It is the
generator that defines and documents the set of supported annotations.

\section1 Domain Model

A domain model object is created, as a result of parsing the IDL document. The domain model defines
the structure of our system as objects. It is built 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 any code generation. You traverse the domain tree and then trigger
your own code generation.

*/