From RTSC-Pedia
[printable version] [offline version] | offline version generated on 25-Jun-2010 20:06 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:
- the target-domain, where specified features become accessible within executable programs (written in C/C++) running on some particular platform; and
- 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 25-Jun-2010 20:06 UTC |