Unoidl syntax description

Contents

Introduction

The unoidl is an idl language (interface description language) which is similar to the corba idl. Idl is a language to describe interfaces and types independently of any programming language and hardware platform. An idl description is used by the idl compiler to generate code for these interfaces in a selected target language. The generated code provide the use of the described interfaces in the selected target language. The mapping of the idl description to the target language was defined in an appropriate language binding.

All possible idl definitions will be described now. The reader who is intimate in C++ programming will see, that the syntax of the idl is similar to the C++ syntax. Because the lexical conventions of the idl and the structure of the definitions have a large degree with the ANSI standard for C++.

Keywords

The following table shows all keywords of the unoidl. All the keywords are reserved and cannot be used as an identifier.

Basetypes

The unoidl support the following basetypes:

any, boolean, byte, char, double, float, hyper, long, short, string, void, unsigned hyper, unsigned long, unsigned short

The values TRUE and FALSE (True and False) are defined for the boolean type. The type byte is a 1 byte type and represents a type which is not modified by the transport to another computer. The representation of the type char can be different on a computer which hardware/software architecture is different. It depends on the representation of the used charset. The type any is a type which can represent all possible idl types.

Comments

Comments are used to describe the source code. If the comment support a special convention, it can be used for automatically generation of documentation. The unoidl support 4 kinds of comments:

• /* comment */

  All characters between /* and */ are ignored by the idl compiler. The characters /* are also ignored, so encapsulated comments (comments in comments) are not allowed.

• // comment end_of_line

  With the characters // starts a comment which ends automatic at the end of the line. All characters after // up to the end_ of_ line character are ignored.

• /** comment */

  The characters /** shows that a special comment for automatic documentation generation begins. This kind of comment will be saved as a special documentation string by the compiler for the idl definition which follow this comment.

• /// comment

  The characters /// shows that a special comment for automatic documentation generation begins. All characters after /// up to the end_ of_ line character are saved as a special documentation string for the next valid idl definition.

Constants

Definition:

const <TypeName> <ConstantName> "=" <Value> ";"

A constant definition begin with the keyword const following by the identifier of a type (base_type), the identifier of the constant and the assignment of a value. The value must be in the range of the used type. The definition ends with a semicolon. It is also possible to assign an expression. You can combine values/expressions of the type [unsigned] hyper| long | short with the operators *, /, %, +, -, <<, >>, &, ^ and | which are known of C++.

Enumeration

Definition:

enum <EnumName> "{" <EnumValue> [= Value] { "," <EnumValue> [= Value] }* "}" ";"

An enumeration definition begin with the keyword enum following by the identifier of the enumeration type. The body of the definition is bound with { } and the complete definition ends with a semicolon. The body exists of an ordered list of identifiers. It is possible to assign such an identifier a value of the type long. The default numbering of the values is linear and begin with 0 and crows with 1. If an identifier has an value, all following identifiers without a value are numbered depending on these last assignment of a value. All enum values of the body are also known in the scope of enumeration type itself.

Structure

Definition:

struct <StructureName> [ ":" <ExistStructureName> ]
"{"
{ <ElementType> <ElementName> ";" }+
"}" ";"

The definition of a structure begins with the keyword struct following by the identifier of the structure. The body of the definition is bound with { } and the complete definition ends with a semicolon. Inside the body it is possible to define some elements. An element definition begins with the identifier of the type following by the identifier of the element name. The definition end with a semicolon. The body of the structure is a new namespace. Inside this namespace it is possible to use all identifiers as names which are definite. It is possible to define an inheritance for the structure. An inheritance will be defined after the name identifier by a colon following an identifier of the parent structure. Inheritance of structures is UNO specific and not CORBA compatible.

Typedef

Definition:

typedef <TypeName> <NewTypeName> ";"

A type definition begins with the keyword typedef following by an identifier of an existing type and the identifier of the new type. The definitions ends with a semicolon

Exception

Definition:

exception <ExceptionName> [ ":" <ExistExceptionName> ]
"{"
{ <ElementType> <ElementName> ";" }*
"}" ";"

The definition of an exception begins with the keyword exception following by the identifier of the exception. The body of the definition is bound with { } and the complete definition ends with a semicolon. Inside the body it is possible to define some members. A member definition begins with the identifier of the type following by the identifier of the member name. The definition end with a semicolon. The body of the structure is a new namespace. Inside this namespace it is possible to use all identifiers as names which are definite. It is possible to define an inheritance for the exception. An inheritance will be defined after the name identifier by a colon following an identifier of the parent exception. Inheritance of exceptions is UNO specific and not CORBA compatible.

Interface

Definition:

"[" uik"("<Uik>")""," ident"(" "\""<InterfaceName>"\"" "," <VersionNummer>")" "]"
interface <InterfaceName> [ ":" <InterfaceName> {, <InterfaceName>}* ]
"{"
{ <typedef> | <struct> | <exception> | <constant> | <enumeration> | <interface>}* { "[" [readonly ","] attribute "]" <TypeName> <AttributeName> { "," <AttributeName>}* ";" }*
{ [ "["const | oneway "]" ] <TypeName> <FunctionName> "(" [ <Parameter> { "," <Parameter>}* ] ")" [ <Raises> ] ";" }*
"}" ";"

<Uik> = xxxxxxxx-xxxx-xxxx-xxxxxxxx-xxxxxxxx ; x Î{0-9a-fA-F}
<Parameter> = "[" in | out | inout "]" <TypeName> <ParameterName>
<Raises> = raises"(" <ExceptionName> { "," <ExceptionName>}* ")"

An interface definition begins with an header which is bound with [ ]. The header consists of an uik (universal interface key) definition and an ident definition. The definition begins with the keyword uik following by a 32 byte number which is split in 5 blocks (8-4-4-8-8 byte) and bound in ( ). The ident definition begins with the keyword ident following by the name of the interface and a version number. After the header follows the keyword interfaces and an identifier for the interface name. Optionally, an inheritance definition can follow. An inheritance definition begins with a colon and one or more identifiers of existing interfaces. The body of the interface is bound with { } and the definition ends with a semicolon.
An interface opens a new namespace. There can be defined typedefs, structs, enums, exceptions, constants and interfaces and also specific definitions for an interface:

• "[" [readonly "," ] attribute "]" <TypeName> <AttributeName> { "," <AttributeName>}* ";"
  An attribute definition begins with a header which is bound with [ ]. In this header the keyword attribute must be defined. Optional the keyword readonly defined that the attribute can only accessed for reading. The header follows an identifier for the attribute type and an identifier for the attribute name or a list of identifiers. The definition ends with a semicolon.

• "["const | oneway "]" ] <TypeName> <FunctionName> "(" [ <Parameter> { "," <Parameter>}* ] ")" [ <Raises> ] ";"
  A function definition begins with an optional header following by an identifier for the return type and an identifier for the function name. The header is bound with [ ] and consists of the flags oneway or const or both. Oneway means that the function is asynchronous and don`t wait for a reply. To use this flag the function must return void, don`t take any out or inout parameters and don`t raise an exception. Const means that the function don`t change the state of the interface. The name of the function follows a parameter definition which is bound in ( ) and a raises expression which is optional.

• <Parameter> = "[" in | out | inout "]" <TypeName> <ParameterName>
  The parameter definition begins with the direction flag which is bound with [ ]. Valid flags for the direction are in ( in parameter), out (out parameter) or inout (in and out parameter). The direction follows an identifier for the parameter type and an identifier for the parameter name. More than one parameter definitions are separated by comma.

• <Raises> = raises"(" <ExceptionName> { "," <ExceptionName>}* ")"
  The raises definition begins with the keyword raises following by one or more identifiers of existing exceptions which are bound with ( ). This named exceptions can be raised during the execution of the function.

Module

Definition:

module <ModuleName>
"{"
{ <typedef> | <struct> | <exception> | <constant> | <enumeration> | <interface> | <module> }*
"}" ";"

A module definition begins with the keyword module following by the identifier of the module. The body of the definition is bound with { } and the complete definition ends with a semicolon. A module opens a new namespace and there can be defined all valid idl definitions.

Service

Definition:

service <ServiceName>
"{"
{ "[" [readonly "," ] property "]" <TypeName> <PropertyName> { "," <PropertyName>}* ";" }*
{ interface <InterfaceName> { "," <InterfaceName> }* ";" }*
{ observes <InterfaceName> { "," <InterfaceName> }* ";" }*
{ needs <ServiceName> { "," <ServiceName> }* ";" }*
"}" ";"

A service definition begins with the keyword service following by an identifier for the name of the service. Services are principally for description and are UNO specific. The body of the definition is bound with { } and the complete definition ends with a semicolon.
Definitions in a service:

• "[" [readonly "," ] property "]" <TypeName> <PropertyName> { "," <PropertyName>}* ";" (see object property definition)

  A property definition begins with a header which is bound with [ ]. In this header the keyword property must be defined. Optional the keyword readonly defined that the property can only accessed for reading. The header follows an identifier for the property type and an identifier for the property name or a list of identifiers. The definition ends with a semicolon.

• interface <InterfaceName> { "," <InterfaceName> }* ";" (see object interface definition)

  An interface definition begins with the keyword interface following by an identifier of an existing interface or a list of identifiers of existing interfaces. This definition in the scope of a service means that the service provides the named interfaces. The definition ends with a semicolon.

• observes <InterfaceName> { "," <interfaceName> }* ";" (see object observes definition)

  An observes definition begins with the keyword observes following by an identifier of an existing interface or a list of identifiers of existing interfaces. This definition in the scope of a service means that the service must observe the named interfaces. The definition ends with a semicolon.

• needs <ServiceName> { "," <ServiceName> }* ";" (see object needs definition)

  A needs definition begins with the keyword needs following by an identifier of an existing service or a list of identifiers of existing services. This definition in the scope of a service means that the service needs the named services. The definition ends with a semicolon.

Author: Jürgen Schmidt ($Date: 2004/10/29 02:01:05 $)
Copyright 2001 Sun Microsystems, Inc., 901 San Antonio Road, Palo Alto, CA 94303 USA.