From RTSC-Pedia

[printable version]  [offline version]

offline version generated on 04-Aug-2010 21:08 UTC

XDCspec - unit-specification

Module and interface specification syntax

A unit specification defines all client-visible programmatic features of a module or interface. While virtually identical with respect to their XDCspec syntax, semantically this pair of programmatic elements are almost opposites: a module is concrete and closed, comprising a public specification accompanied by a conforming implementation; an interface is abstract and open, comprising only a public specification which others may import and ultimately implement. In general, the specification of a module or interface can inherit features from exactly one other (interface) specification, which itself can inherit additional features in the same manner -- as if the latter’s cumulative set of features had been directly defined with the unit specification of its inheritor.

The features defined within the scope of a unit partition themselves into two main groups: module-wide features, which are associated with a solitary programmatic object encapsulating the implementation of some concrete module; and per-instance features, which are associated with a family of programmatic objects individually created and manipulated by the same underlying module. Aside from auxiliary definitions of supporting constants and types (deemed module-wide for convenience), features with a meaningful run-time presence in the underlying implementation -- assignable configuration parameters along with callable functions -- can participate in either category. As with packages, special documentation comments can be associated with the module/interface as a whole as well as with any named feature defined within its scope.

In the general case, a single unit specification for a module or interface defines a presence in two congruent programming domains:

1. the target-domain, where specified features become accessible within executable programs (written in C/C++) running on some particular platform; and
2. the meta-domain, where specified features become accessible within hosted scripts (written in XDCscript) used to configure these very same target programs ahead of their execution. In some cases, the specification of a particular module or interface can be restricted to the meta-domain -- useful when constructing configuration "facades" atop legacy content as well as when distributing host-based meta-content for use in a broader range of scripting contexts.

unit-specification

//! @xdoc
metaonly? unit-category UnitNameinherited-interface?{
    module-wide-feature* [ instance:per-instance-feature*]?
}[;]?
//! @xdoc

inherited-interface

inherits qualified-unit-name

qualified-unit-name

[qualified-package-name .]? UnitName

module-wide-feature

//! @xdoc
[auxiliary-definition | config-parameter | function-declaration]

per-instance-feature

//! @xdoc
[config-parameter | function-declaration]

• A qualified-unit-name effectively extends the (already) globally-unique name of the unit's containing package. If the qualified-package-name prefix is absent, the current package name is presumed.
• A unit-specification resides in a source file named UnitName.xdc, found in the directory of its containing package.
• Each module-wide-feature or per-instance-feature introduces an individual feature with the scope of the current unit, all of which must be uniquely named. Features with the same name may only appear in different units.
• An inherited-interface designates a single interface whose features are introduced within the scope of the current unit. Any module or interface can optionally inherit features from another interface, so long as the inherits-relation among all units remains acyclic.
• Each unit manifests itself in both the target- and meta-programming domains, unless designated metaonly. As a rule, inheritors of metaonly interfaces must themselves be metaonly modules or interfaces.

[printable version]  [offline version]

offline version generated on 04-Aug-2010 21:08 UTC