//
// Copyright (c) 2009-2014,2017 LAAS/CNRS
// All rights reserved.
//
// Permission to use, copy, modify,  and distribute this software for any
// purpose with or without fee is hereby granted, provided that the above
// copyright notice and this permission notice appear in all copies.
//
// THE  SOFTWARE  IS  PROVIDED  "AS  IS" AND  THE  AUTHOR  DISCLAIMS  ALL
// WARRANTIES  WITH  REGARD  TO   THIS  SOFTWARE  INCLUDING  ALL  IMPLIED
// WARRANTIES  OF MERCHANTABILITY  AND  FITNESS. IN  NO  EVENT SHALL  THE
// AUTHOR BE  LIABLE FOR ANY SPECIAL, DIRECT,  INDIRECT, OR CONSEQUENTIAL
// DAMAGES OR ANY DAMAGES WHATSOEVER  RESULTING FROM LOSS OF USE, DATA OR
// PROFITS,  WHETHER  IN  AN  ACTION  OF CONTRACT,  NEGLIGENCE  OR  OTHER
// TORTIOUS  ACTION, ARISING  OUT OF  OR IN  CONNECTION WITH  THE  USE OR
// PERFORMANCE OF THIS SOFTWARE.
//
//                                      Anthony Mallet on Mon May 31 2010
//
//

ifdef::sidebartoc[]
include::_Sidebar.adoc[]
endif::[]

Component description file
--------------------------

This chapter describes the syntax of the `genom` component description
file. This file has by convention a name ending with the `.gen` suffix. It is
thus often called the `.gen` file (or `dot gen`).

The `dot gen` file contains the complete formal description of a component in
terms of services and data types it provides. Such a description completely
defines the interface and the internals of a component. The syntax of this
files is a mix between a subset of the OMG IDL for data types definitions and
genom specific constructs.

The `dot gen` file is pre-processed by a pre-processor that follows the
standard of the `C` preprocessor. See the
link:preprocessing{outfilesuffix}[Preprocessing] section for details.  The
complete link:grammar{outfilesuffix}[grammar definition] is available for
reference, but the most important constructs are detailed in the following
sections.

The description of the `dot gen` grammar uses a syntax notation that is similar
to `EBNF` (Extended Backus-Naur Format).  The following table lists the symbols
used in this format and their meaning.

.`dotgen` 'EBNF' symbols
[width="60%",cols="^,3",frame="topbot",options="header"]
|===========================================================================
|Symbol       | Meaning
|`::=`        | Definition
|`\|`         | Alternation
|`text`       | Non terminals
|`"text"`     | Terminals
|`( ... )`    | Grouping
|`{ ... }`    | Repetitions: may occur zero or any number of times
|`[ ... ]`    | Option: may occur zero or one time
|===========================================================================


=== Topics


* link:preprocessing{outfilesuffix}[Preprocessing]:
Inclusion of definitions from other specifications

* link:specification{outfilesuffix}[Elements of a description file]:
Basic elements of a `genom3` specification

* link:idltype{outfilesuffix}[Data type and constant definitions]:
Definition of new types and constant values

* link:module{outfilesuffix}[Module declaration]:
Namespace for type definitions

* link:component{outfilesuffix}[Component declaration]

* link:interface{outfilesuffix}[Interface declaration]

* link:ids{outfilesuffix}[IDS declaration]:
Private, shared global data.

* link:port{outfilesuffix}[Port declaration]:
Published and imported data.

* link:task{outfilesuffix}[Task declaration]:
Execution context for running actual code.

* link:service{outfilesuffix}[Service declaration]:
Attributes, functions, activities and their parameters.

* link:codel{outfilesuffix}[Codel declaration]

* link:keywords{outfilesuffix}[Identifiers and reserved keywords]:
Words with a special meaning

* link:pragma{outfilesuffix}[Pragmas]:
Providing additional information to the parser

* link:grammar{outfilesuffix}[Grammar reference]:
Extensive `genom3` EBNF grammar reference
