path: root/src/doc/qtivi/src/idl-syntax.qdoc

/****************************************************************************
**
** Copyright (C) 2017 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}
*/