Chapter 13 Packages

The import-clause makes public classes and other public definitions declared in some package available for use by shorter names in a class or a package. It is the only way of referring to definitions declared in some other package for use inside an encapsulated package or class.

[Import-clauses in a package or class fill the following two needs:

• •

  Making definitions from other packages available for use (by shorter names) in a package or class.

• •

  Explicit declaration of usage dependences on other packages.

]

An import-clause can occur in one of the following five syntactic forms:

import packagename; (qualified import)

import [packagename.]definitionname; (single definition import)

import [packagename.]{def1,def2,…defN}; (multiple definition import)

import packagename.*; (unqualified import)

import shortpackagename = packagename; (renaming import)

import shortpackagename = [packagename.]definitionname; (renaming single def. import)

Here packagename is the fully qualified name of the imported package including possible dot notation and definitionname is the name of an element in a package. The multiple definition import is equivalent to multiple single definition imports with corresponding packagename and definition names.

Packages/classes may be represented in the hierarchical structure of the operating system [the file system]. For classes with version information see also section 18.8.3. The nature of such an external entity falls into one of the following two groups:

• •

  Directory in the file system.

• •

  File in the file system.

Each Modelica file in the file-system is stored in UTF-8 format (defined by The Unicode Consortium; http://www.unicode.org) and may start with the UTF-8 encoded byte order mark (0xef 0xbb 0xbf); this is treated as white-space in the grammar. [Tools may also store classes in data-base systems, but that is not standardized.]

In order to reference external resources from documentation (such as links and images in html-text) and/or to reference images in the Bitmap annotation (see section 18.6.5.6). URIs should be used, for example file:/// and the URI scheme modelica:// which can be used to retrieve resources associated with a package. [Note scheme names are case-insensitive, but the lower-case form should be used, that is ‘Modelica://’ is allowed but ‘modelica://’ is the recommended form.]

The Modelica-scheme has the ability to reference a hierarchical structure of resources associated with packages. The same structure is used for all kind of resource references, independent of use (external file, image in documentation, bitmap in icon layer, and link to external file in the documentation), and regardless of the storage mechanism.

Any Modelica-scheme URI containing a slash after the package-name is interpreted as a reference to a resource. The ‘authority’ portion of the URI is interpreted as a fully qualified package name and the path portion of the URI is interpreted as the path (relative to the package) of the resource. Each storage scheme can define its own interpretation of the path (but care should be taken when converting from one storage scheme or when restructuring packages that resource references resolve to the same resource). Any storage scheme should be constrained such that a resource with a given path should be unique for any package name that precedes it. The first part of the path may not be the name of a class in the package given by the authority.

When Modelica packages are stored hierarchically in a file-system (i.e. package A in a directory A containing ”package.mo”) the resource ”modelica://A/Resources/C.jpg” should be stored in the file ”A/Resources/C.jpg”, it is not recommend to use ”modelica://A.B/C.jpg” for referencing resources; it could be stored in the file ”A/B/C.jpg” - which is counter-intuitive if A.B is stored together with A. When Modelica packages are stored in other formats a similar mapping should be defined, such that a resource with a given path should be unique for any package name that precedes it. The first part of the path may not be the name of a class in the package given by the authority. As above for ”Modelica 3.2.1/package.mo” i.e. resources starting from ”Modelica 3.2.1”, and ”modelica://Modelica.Mechanics/C.jpg” is ”Modelica 3.2.1/Mechanics/C.jpg” - regardless of whether Modelica.Mechanics is stored in ”Modelica 3.2.1/package.mo”, ”Modelica 3.2.1/Mechanics/package.mo”, or ”Modelica 3.2.1/Mechanics.mo”.

For a Modelica-package stored as a single file, ”A.mo”, the resource ”modelica://A/C.jpg” refers to a file ”C.jpg” stored in the same directory as ”A.mo”, but using resources in this variant is not recommended since multiple packages will share resources.

In case the class-name contains quoted identifiers, the single-quote ”‘” and any reserved characters (“:”, “/”, “?”, “#”, “[“, “]”, “@”, “!”, “$”, “&”, “(“, “)”, “*”, “+”, “,”, “;”, “=”) should be percent-encoded as normal in URIs.

[Example:

Consider a top-level package Modelica and a class Mechanics inside it, a reference such as modelica://Modelica.Mechanics/C.jpg is legal, while modelica://Modelica/Mechanics/C.jpg is illegal. The reference modelica://Modelica.Mechanics/C.jpg must also refer to a different resource than modelica://Modelica/C.jpg.]

The top-level scope implicitly contains a number of classes stored externally. If a top-level name is not found at global scope, a Modelica translator shall look up additional classes in an ordered list of library roots, called MODELICAPATH. [The implementation of MODELICAPATH is tool dependent. In order that a user can work in parallel with different Modelica tools, it is advisable to not have this list as environment variable, but as a setting in the respective tool. Since MODELICAPATH is tool dependent, it is not specified in which way the list of library roots is stored. Typically, on a Windows system MODELICAPATH is a string with path names separated by “;” whereas on a Linux system it is a string with path names separated by a “:”.]

In addition a tool may define an internal list of libraries, since it is in general not advisable for a program installation to modify global environment variables. The version information for a library (as defined in section 18.8) may also be used during this search to search for a specific version of the library (e.g. if Modelica library version 2.2 is needed and the first directory in MODELICAPATH contain Modelica library version 2.1, whereas the second directory contains Modelica version 2.2, then Modelica library version 2.2 is loaded from the second directory.).

[The first part of the path A.B.C (i.e., A) is located by searching the ordered list of roots in MODELICAPATH. If no root contains A the lookup fails. If A has been found in one of the roots, the rest of the path is located in A; if that fails, the entire lookup fails without searching for A in any of the remaining roots in MODELICAPATH.]