packages.tex

\chapter{Packages}\label{packages}

Packages in Modelica may contain definitions of constants and
classes including all kinds of specialized classes, functions, and
subpackages. By the term subpackage we mean that the package is declared
inside another package, no inheritance relationship is implied.
Parameters and variables cannot be declared in a package. The
definitions in a package should typically be related in some way, which
is the main reason they are placed in a particular package. Packages are
useful for a number of reasons:
\begin{itemize}
\item
  Definitions that are related to some particular topic are typically
  grouped into a package. This makes those definitions easier to find
  and the code more understandable.
\item
  Packages provide encapsulation and coarse-grained structuring
  that reduces the complexity of large systems. An important example is
  the use of packages for construction of (hierarchical) class
  libraries.
\item
  Name conflicts between definitions in different packages are
  eliminated since the package name is implicitly prefixed to names of
  definitions declared in a package.
\item
  Information hiding and encapsulation can be supported to some
  extent by declaring \lstinline!protected! classes, types, and other
  definitions that are available only inside the package and therefore
  inaccessible to outside code.
\item
  Modelica defines a method for locating a package by providing a
  standard mapping of package names to storage places, typically file or
  directory locations in the file system.
\end{itemize}

\section{Package as Specialized Class}\label{package-as-specialized-class}

The package concept is a specialized class (\cref{specialized-classes}), using the
keyword \lstinline!package!.

\section{Importing Definitions from a Package}\label{importing-definitions-from-a-package}

The \lstinline!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.

\begin{nonnormative}
The \lstinline!import!-clauses in a package or class fill the following two needs:
\begin{itemize}
\item
  Making definitions from other packages available for use (by shorter names) in a package or class.
\item
  Explicit declaration of usage dependences on other packages.
\end{itemize}
\end{nonnormative}

%TODO-FORMAT Should be formatted using tabs or tabular?
An \lstinline!import!-clause\indexinline{import} can occur in one of the following syntactic forms:

% Note a syntactic form cannot be written as a single \lstinline due to LaTeXML problem reported here:
%   https://github.com/brucemiller/LaTeXML/issues/1274 (marked as fixed as of commit 80d7940)
% Instead, we need to break up the \lstinline in mysterious ways.  Be sure to check that the generated HTML
% looks OK when making changes!

\lstinline!import $\mathit{definitionname}$;! (qualified import of top-level definition)

\lstinline!import $\mathit{packagename}$.!% Break up \lstinline as workaround for LaTeXML issue described above.
\lstinline!$\mathit{definitionname}$;! (qualified import)

\lstinline!import $\mathit{packagename}$.{$\mathit{def}_{1}$, $\mathit{def}_{2}$, $\ldots$, $\mathit{def}_{n}$};! (multiple definition import)

\lstinline!import $\mathit{packagename}$.*;! (unqualified import)

\lstinline!import $\mathit{shortname}$ = $\mathit{definitionname}$;! (renaming import of top-level definition)

\lstinline!import $\mathit{shortname}$ = $\mathit{packagename}$.!% Break up \lstinline as workaround for LaTeXML issue described above.
\lstinline!$\mathit{definitionname}$;! (renaming import)

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

\subsection{Lookup of Imported Names}\label{lookup-of-imported-names}

This section only defines how the imported name is looked up in the \lstinline!import!-clause.
For lookup in general -- including how \lstinline!import!-clauses are used -- see \cref{static-name-lookup}.

Lookup of the name of an imported package or class deviates from the normal lexical lookup.
For example, consider \lstinline!A.B.C! in the \lstinline!import!-clauses \lstinline!import A.B.C;!, \lstinline!import D = A.B.C;!, or \lstinline!import A.B.C.*;!.
Here, lookup starts with the lexical lookup of the first part of the name (\lstinline!A!) at the top level.

Qualified \lstinline!import!-clauses may only refer to packages or elements of packages, i.e., in \lstinline!import A.B.C;! or \lstinline!import D = A.B.C;!, \lstinline!A.B! must be a package.
Unqualified \lstinline!import!-clauses may only import from packages, i.e., in \lstinline!import A.B.*;!, \lstinline!A.B! must be a package.

\begin{nonnormative}
In \lstinline!import A;! the class \lstinline!A! can be any class which is an element of the unnamed top-level package.
\end{nonnormative}

\begin{nonnormative}
For example, if the package \lstinline!ComplexNumbers! would have been declared as a subpackage inside the package \lstinline!Modelica.Math!, its fully qualified name would be
\lstinline!Modelica.Math.ComplexNumbers!.  $\mathit{definitionname}$ is the simple name without dot notation of a single definition that is imported.  A $\mathit{shortname}$ is
a simple name without dot notation that can be used to refer to the package after import instead of the presumably much longer $\mathit{packagename}$.

The forms of \lstinline!import! are exemplified below assuming that we want to access the addition operation of the hypothetical package \lstinline!Modelica.Math.ComplexNumbers!:
\begin{lstlisting}[language=modelica]
import Modelica.Math.ComplexNumbers;       // Accessed by ComplexNumbers.Add
import Modelica.Math.ComplexNumbers.Add;   // Accessed by Add
import Modelica.Math.ComplexNumbers.{Add,Sub}; // Accessed by Add and Sub
import Modelica.Math.ComplexNumbers.*;     // Accessed by Add
import Co = Modelica.Math.ComplexNumbers;  // Accessed by Co.Add
\end{lstlisting}
\end{nonnormative}

\subsection{Rules for Import-Clauses}\label{summary-of-rules-for-import-clauses}\label{rules-for-import-clauses}

The following rules apply to \lstinline!import!-clauses:
\begin{itemize}
\item
  The \lstinline!import!-clauses are \emph{not} inherited.
\item
  The \lstinline!import!-clauses are not named elements of a class or package.
  This means that \lstinline!import!-clauses cannot be changed by modifiers or redeclarations.
\item
  The \emph{order} of \lstinline!import!-clauses does not matter.
\item
  One can only import \emph{from} packages, not from other kinds of classes.
  Both packages and classes can be imported \emph{into} i.e., they may contain \lstinline!import!-clauses.
\item
  An imported package or definition should always be referred to by its fully qualified name in the \lstinline!import!-clause.
\item
  Multiple qualified \lstinline!import!-clauses shall not have the same import name (see \cref{simple-name-lookup}).
\end{itemize}

\section{The Modelica Library Path -- MODELICAPATH}\label{the-modelica-library-path-modelicapath}

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 \lstinline!MODELICAPATH!\indexinline{MODELICAPATH}.

\begin{nonnormative}
The implementation of \lstinline!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 \lstinline!MODELICAPATH! is tool dependent, it is not specified in which way
the list of library roots is stored.  Typically, on a Windows system \lstinline!MODELICAPATH! is a string with path names separated by `\filename{;}' whereas on a Linux system
it is a string with path names separated by a `\filename{:}'.
\end{nonnormative}

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 \cref{annotations-for-version-handling}) 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 \lstinline!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.).

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

If during lookup a top-level name is not found in the unnamed top-level scope, the search continues in the package hierarchies stored in these directories.

\begin{example}
\Cref{fig:roots} below shows an example \lstinline!MODELICAPATH! = \filename{"C:\textbackslash{}library;C:\textbackslash{}lib1;C:\textbackslash{}lib2"}, with three
directories containing the roots of the package hierarchies \lstinline!Modelica!, \lstinline!MyLib!, and \lstinline!ComplexNumbers!.  The first two are represented as
the subdirectories \filename{C:\textbackslash{}library\textbackslash{}Modelica} and \filename{C:\textbackslash{}lib1\textbackslash{}MyLib}, whereas the third is stored
as the file \filename{C:\textbackslash{}lib2\textbackslash{}ComplexNumbers.mo}.

\begin{figure}[H]
  \begin{center}
    \includegraphics{modelicapath}
  \end{center}
  \caption{Roots of package hierarchies, e.g., \lstinline!Modelica!, \lstinline!MyLib!, and \lstinline!ComplexNumbers! in
  \lstinline!MODELICAPATH! = \filename{"C:\textbackslash{}library;C:\textbackslash{}lib1;C:\textbackslash{}lib2"}.}
  \label{fig:roots}
\end{figure}

Assume that we want to access the package \lstinline!MyLib.Pack2! in \cref{fig:roots} above, e.g.\ through an \lstinline!import!-clause \lstinline!import MyLib.Pack2;!.
During lookup we first try to find a package \lstinline!MyLib! corresponding to the first part of the name in the import-statement.
It is not found in the top-level scope since it has not previously been loaded into the environment.

Since the name was not found in the top-level scope the search continues in the directories in the \lstinline!MODELICAPATH! in the specified order.  For the search to succeed,
there must be a subdirectory \filename{MyLib} or a file \filename{MyLib.mo} in one of the directories mentioned in the \lstinline!MODELICAPATH!.  If there is no such
subdirectory or file, the lookup fails.  If \filename{MyLib} is found in one of the directories, the rest of the name, in this case \lstinline!Pack2!, is located in
\filename{MyLib}.  If that fails, the entire lookup fails without continuing the search in possibly remaining directories.

In this example the name matches the subdirectory named \filename{MyLib} in the second directory \filename{C:\textbackslash{}lib1} mentioned in the \lstinline!MODELICAPATH!.
This subdirectory must have a file \filename{package.mo} containing a definition of the package \lstinline!MyLib!, according to the Modelica rules on how to map a package
hierarchy to the file system.  The subpackage \lstinline!Pack2! is stored in its own subdirectory or file in the subdirectory \filename{MyLib}.  In this case the search
succeeds and the package \lstinline!MyLib.Pack2! is loaded into the environment.
\end{example}


\section{File System Mapping of Package/Class Hierarchy}\label{mapping-package-class-structures-to-a-hierarchical-file-system}\label{file-system-mapping-of-package-class-hierarchy}

Packages/classes may be represented in the hierarchical structure of the
operating system (the file system). For classes with version
information see also \cref{mapping-of-versions-to-file-system}. The nature of such an external
entity falls into one of the following two groups:
\begin{itemize}
\item
  Directory in the file system.
\end{itemize}

\begin{itemize}
\item
  File in the file system.
\end{itemize}

Each Modelica file in the file-system is stored in UTF-8 format (defined by The Unicode Consortium; \url{https://unicode.org}).  A deprecated feature is that the file may start with the UTF-8 encoded BOM (byte order mark; \lstinline!0xef 0xbb 0xbf!); this is treated as white-space in the grammar.  Since the use of BOM is deprecated, tools can ignore any BOM when reading, and it is recommended to never write it.

\begin{nonnormative}
Tools may also store classes in data-base systems, but that is not standardized.
\end{nonnormative}

\subsection{Directory Hierarchy Mapping}\label{mapping-a-package-class-hierarchy-into-a-directory-hierarchy-structured-entity}\label{directory-hierarchy-mapping}

A directory shall contain a node, the file \filename{package.mo}.
The node shall contain a \lstinline[language=grammar]!stored-definition! that defines a class \lstinline!A! with a name matching the name of the structured entity.

\begin{nonnormative}
The node typically contains documentation and graphical information for a package, but may also contain additional elements of the class \lstinline!A!.
\end{nonnormative}

A directory may also contain one or more sub-entities (directories or
files). The sub-entities are mapped as elements of the class defined by
their enclosing structured entity.  Two sub-entities shall not define classes with identical names

\begin{example}
If directory \filename{A} contains the three files \filename{package.mo}, \filename{B.mo} and \filename{C.mo}, the classes defined are \lstinline!A!,
\lstinline!A.B!, and \lstinline!A.C.!
\end{example}

\begin{example}
A directory shall not contain both the sub-directory \filename{A} and the file \filename{A.mo}.
\end{example}

In order to preserve the order of sub-entities it is advisable to create
a file \filename{package.order} where each line contains the name of one class or
constant (using its Modelica \lstinline!IDENT! form). If a \filename{package.order} is present when reading a structured entity
the classes and constants are added in this order; if the contents does
not exactly match the classes and constants in the package, the
resulting order is tool specific and a warning may be given. Classes and
constants that are stored in \filename{package.mo} are also present in
\filename{package.order} but their relative order should be identical to the one in
\filename{package.mo} (this ensures that the relative order between classes and
constants stored in different ways is preserved).

\subsection{Single File Mapping}\label{mapping-a-package-class-hierarchy-into-a-single-file-nonstructured-entity}\label{single-file-mapping}

When mapping a package or class-hierarchy to a file (e.g.\ the file \filename{A.mo}), that file shall only define a single class \lstinline!A! with a
name matching the name of the nonstructured entity. In a file hierarchy the files shall have the extension \filename{.mo}.

A \filename{.mo} file defining more than one class cannot be part of the mapping
to file-structure and it is an error if it is loaded from the
\lstinline!MODELICAPATH!.

\subsection{The within Clause}\label{the-within-clause}

A \lstinline!within!-clause has the following syntax:
\begin{lstlisting}[language=grammar]
  within [ packageprefixname ] ";"
\end{lstlisting}%
\indexinline{within}
A non-top-level entity shall begin with a \lstinline!within!-clause which for the class defined in the entity specifies the location in the Modelica class hierarchy.
A top-level class may contain a \lstinline!within!-clause with no name.
For a sub-entity of an enclosing structured entity, the \lstinline!within!-clause shall designate the class of the enclosing entity; and this class must exist and must not have been defined using a short class definition.

\begin{example}
The subpackage \lstinline!Rotational! declared within
\lstinline!Modelica.Mechanics! has the fully qualified name
\lstinline!Modelica.Mechanics.Rotational!, which is formed by concatenating
the packageprefixname with the short name of the package. The
declaration of \lstinline!Rotational! could be given as below:
\begin{lstlisting}[language=modelica]
within Modelica.Mechanics;
package Rotational // Modelica.Mechanics.Rotational
  $\ldots$
\end{lstlisting}
\end{example}

\section{External Resources}\label{external-resources}

In order to reference external resources from documentation (such as links and images in html-text) and/or to reference images in the \lstinline!Bitmap! annotation (see \cref{bitmap}).
Absolute URIs should be used, for example \filename{file:///} and the URI scheme \filename{modelica://} which can be used to retrieve resources associated with a package.
According to the URI specification scheme names are case-insensitive, but the lower-case form should be used, that is \filename{Modelica://} is allowed but \filename{modelica://} is the recommended form.

The Modelica-scheme\index{Modelica!URI scheme}\index{URI!Modelica} 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 \emph{authority} portion of the
URI is interpreted as a fully qualified package name and the \emph{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 shall 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 \lstinline!A! in a directory \filename{A} containing \filename{package.mo}) the resource
\filename{modelica://A/Resources/C.jpg} should be stored in the file \filename{A/Resources/C.jpg}, it is not recommend to use \filename{modelica://A.B/C.jpg} for referencing
resources; it could be stored in the file \filename{A/B/C.jpg} -- which is counter-intuitive if \lstinline!A.B! is stored together with \lstinline!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 shall not be the name of a class in the package given by the authority.  As above for \filename{Modelica 3.2.1/package.mo} i.e.\ resources starting from
\filename{Modelica 3.2.1}, and \filename{modelica://Modelica.Mechanics/C.jpg} is \filename{Modelica 3.2.1/Mechanics/C.jpg} -- regardless of whether \lstinline!Modelica.Mechanics!
is stored in \filename{Modelica 3.2.1/package.mo}, \filename{Modelica 3.2.1/Mechanics.mo}, or \filename{Modelica 3.2.1/Mechanics/package.mo}.

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

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

\begin{example}
Consider a top-level package \lstinline!Modelica! and a class
\lstinline!Mechanics! inside it, a reference such as
\filename{modelica://Modelica.Mechanics/C.jpg} is legal, while
\filename{modelica://Modelica/Mechanics/C.jpg} is illegal.
The references \filename{modelica://Modelica.Mechanics/C.jpg} and \filename{modelica://Modelica/C.jpg} must also refer to two distinct resources.
\end{example}