7.7 Library mechanisms

7.7.1 Introduction

This chapter describes all language features that are relevant to the structuring of collections of scenarios and supporting infrastructure.

This includes scenario libraries, domain model extensions, and helper libraries.

This chapter is targeted at library mechanisms for the language and does not consider scenario databases.

7.7.2 Scenario entry point

The scenario entry point is the initial scenario that is selected for scenario execution. It is instantiated first and starts the overall execution.

For ASAM OpenSCENARIO it is defined by implementation how the scenario entry point is selected from the available scenarios in a file. This allows implementations to experiment with the best ways to select this entry point while still allowing full flexibility in a scenario and scenario file reuse.

A future version of ASAM OpenSCENARIO is likely to provide more standardized and advanced facilities for entry point selection.

7.7.3 Import mechanism

To structure source code, it is good practice to split the code into manageable parts and put these parts into separate files. The files can then be recombined using an import mechanism.

The import mechanism built into ASAM OpenSCENARIO allows the content of one file (the referenced file) to be reused in another file (the referencing file). This mechanism also works recursively, so that a referenced file can refer to further referenced files.

7.7.3.1 The import statement

The import statement allows importing a file.

The import statement makes all definitions found in the referenced file effective as if they had been included in the referencing file:

Any prelude statements found in the referenced file are treated as having occurred at the textual location of the import statement.
Any other statements are treated as having appeared before all non-prelude statements in the referencing file, taking the order of imports into account, meaning non-prelude statements from earlier import statements precede those from later import statements.

The file to be imported can be specified inside the import statement as a string literal or using identifiers.

In all cases, a file that is referenced multiple times (either directly or transitively) is only imported once. The import occurs at the place in the transitive reference chain that is first according to depth-first traversal: All later references to the same file result in no further import occurring.

The implementation shall detect multiple references as described using the mechanisms the implementation considers necessary. In case no other mechanism is found more suitable, an implementation may consider two files to be the same if they have identical content.

7.7.3.1.1 Import using string literals

If the file is specified using a string literal, then the file specification is considered to be a Uniform Resource Identifier (URI). Relative URIs are resolved relative to the location of the referencing file.

Implementations shall support the file URI scheme. Implementations may support more URI schemes.

It is recommended to use a file extension of .osc to identify files of this version of ASAM OpenSCENARIO. This differentiates such files from the XML-based ASAM OpenSCENARIO 1.2.0 files using the .xosc file extension.

7.7.3.1.2 Import using identifiers

If the file is specified using one or more identifiers separated by a period (.), the file specification is considered to be a module reference and is resolved to a file specification by the implementation in an implementation-specific manner. This mechanism can include user- and system-defined library search paths.

Any structured identifier that starts with the osc identifier is reserved for use by this version and future versions of ASAM OpenSCENARIO (see also Section 7.7.3.2, “Importing the standard library”).

Note that the reserved identifier osc is different from the file extension .osc that is by default used for files of ASAM OpenSCENARIO, even though both use the same three-letter abbreviation.

The current specification of how module references are resolved is intentionally left non-specific for this release in order to allow implementations to evolve with actual usage practice. Future versions of the standard are likely to encode best practices when actual practice is clearer and the other components of a module system are in place. For maximum portability across implementations the URI-based string specifications can be used.

Code 1. Examples of file import statements

# URI-based import statements
import "foo/bar.osc"
import "file:///c:/Users/someone/src/foo/bar.osc"
import "file:/c:/Users/someone/src/foo/bar.osc"
import "/c:/Users/someone/src/foo/bar.osc"
import "file:///home/someone/src/foo/bar.osc"
import "file:/home/someone/src/foo/bar.osc"
import "/home/someone/src/foo/bar.osc"

# Identifier-based import statements
import osc.standard   # Imports the standard library, see next section.
import foo.bar        # Imports a module foo.bar in some implementation defined way

7.7.3.2 Importing the standard library

The ASAM OpenSCENARIO standard library is described in Section 8.14, "Standard library". Any scenario file that is to use standard library facilities must import the standard library with the following import statement:

Code 2. Import statement for use of standard library

import osc.standard

This will ensure that the definitions of the standard library are accessible. Whether an implementation implements this by importing some variant of the standard.osc file provided as part of this standard, or through any other means (e.g. by providing access to built-in definitions) is left to the implementation.