modelica-uris.md

Modelica URIs

The Modelica URI format is extended to give meaning to the forms described below. (Examples and more details were included in the old email thread, and might be of interest to also include here.)

The design originates from the structure of a general URI. Quoting Wikipedia:

URI = scheme:[//authority]path[?query][#fragment]

Users that are unsure about the details of the general URI syntax are recommended to try one of the many freely available online tools for URI parsing, such as: https://www.freeformatter.com/url-parser-query-string-splitter.html

Basic structure

The path part of a Modelica URI is denoted the Modelice URI's class reference, and unlike the old Modelica URI format, qualified Modelica class names use the normal URI path segment separator / instead of ..

The new format takes advantage of the authority being optional. The meaning of a non-empty authority is currently reserved for the deprecated form of a Modelica URI. An empty authority cannot be mistaken for the deprecated form, and is allowed in the new form as an alternative to not specifying the authority at all.

As usual, some characters need to be URL encoded when put in a URI. For instance, the Modelica class .Slashy.'Foo/Bar'.Baz is referenced like so:

• modelica:/Slashy/'Foo%2FBar'/Baz

Class reference

This section presents a couple of alternative designs, meant to be discussed in the language group before deciding which one to proceed with.

Before going into the alternative new designs, let us first mention the current form:

• modelica://host/… (non-empty host) — This is the form defined today, becoming deprecated as of this MCP. In this MCP, this is referred to as the deprecated form (of a Modelica URI).
  • Example: modelica://Modelica.Electrical.Analog/media/foo.png

Relative Modelica URIs and the class tree context

Among the proposed forms of class references below, there are some that are only meaningful relative to a context given by a position in the Modelica class tree. These forms can only be used where a class tree context is given. It is an error if class reference relative to the class tree context doesn't resolve to a class within the same top level package as that of the context — references to resources in a different top level package must use the fully qualified form. The class tree context can be given in one of two ways:

• A string literal (or a substring thereof) appearing in a Modelica class definition, and in a position where a Modelica URI is given special meaning. This generally excludes Modelica string literals denoting normal Modelica String values — a Modelica tool does not need to keep track of the origin of all string values in the form of Modelica URIs in order to preserve the class tree context. Instead, it is in the context of certain annotations that a string literal can be in a position where a Modelica URI is expected, as in the href of an a tag in the Documentation annotation.
• The resolveURI operator, also introduced by this MCP.

A separate rationale is given for the inclusion of relative class references in this MCP.

Base proposal: No authority, slash-separation, and Modelica lookup

These are the different ways of referencing a class, where the host, fullclass, and relclass represent a slash-separated Modelica class reference (that is, Modelica identifiers, separated by the forward slash (/) charater):

• modelica:/fullclass — Class given by its fully qualified name. It is an error if fullclass does not refer to an existing class.
  • Example: modelica:/Modelica/Electrical/Analog
  • Example: modelica:///Modelica/Electrical/Analog (empty authority; the fullclass form is the only possible form of class reference when authority is present)
• modelica:relclass — Class given by lookup of relclass in the class tree. Requires class tree context, and it is an error if relclass doesn't resolve to an existing class.
  • Example: modelica:Examples
  • Example: modelica: (empty relclass)
  • Example: modelica:?figure=Disturbances&plot=Wind (empty relclass)
• modelica:./relclass — Same as modelica:./relclass, possibly useful to add clarity.
  • Example: modelica:./Examples
  • Example: modelica:. (empty relclass)
  • Wrong: modelica:///. (malformed absolute reference with fullclass /.)
  • Wrong: modelica:///./Examples (malformed absolute reference with fullclass /./Examples)
• modelica:~/relclass — Similar to the form above, but lookup of relclass is made from the point of the nearest enclosing encapsulated class, or the current top level class in case there is no enclosing encapsulated class. For the MSL, where class encapsultion is currently not used much at all, this provides a convenient way to access resources organized in a hierarchy which is separate from the package hierarchy.
  • Example: modelica:~/Icons
  • Example: modelica:~?resource=images/logo.png (empty relclass)
  • Example: modelica:~/Documentation?view=info#introduction

The forms containing relclass are referred to as the lookup-based forms (of a Modelica URI). The form with fullclass is referred to as the fully qualified form (of a Modelica URI).

Lookup-free variation: Staying in the class tree

While powerful and tightly coupled with the rest of the Modelica language, the lookup-based forms also come with some disadvantages:

• Implementation and execution complexity: Performing lookup requires a significant amount of Modelica know-how to get it right, and performing the operation is not cheap.
• There is currently no Modelica URIs relying on resources associated with the class in the instance tree; all current resources are associated with the class in the class tree, but locating a class in the class tree could be much simpler than performing a normal Modelica lookup.

This leads to the alternative approach of making class references only through the class tree:

• modelica:relclass — Class given by appending relclass to the class tree context, and it is an error if relclass doesn't resolve to an existing class.
• modelica:~/relclass — Similar to the form above, but relclass is appended to the nearest enclosing encapsulated class, or the current top level class in case there is no enclosing encapsulated class. For the MSL, this would just as fine as the lookup-based form.
• modelica:{../}relclass (one or more leading '..' path segments) — Similar to the '.' form, but moving one level up the class tree with each '..' segment, and then appending relclass. This is useful for locating sibling classes in a relative manner without depending on class encapsulation.
  • Example: modelica:../Resistor

Class references with '.' separator

While not following the structure of a general URI, it would also be possible to define the new Modelica URIs with the class reference using . as separator rahter than /. A separate rationale is given for the current proposal of not using ..

By sacrificing the ability to include a relative file path at the end of the URI path, one could also allow a mix of / and . separators. The following would all be equivalent:

• modelica:/Modelica/Electrical/Analog/Examples/ChuaCircuit
• modelica:.Modelica.Electrical.Analog.Examples.ChuaCircuit
• modelica:/Modelica.Electrical.Analog/Examples.ChuaCircuit

Variations of the class reference can still be made by prepending the same special leading segments to the path, for example:

• modelica:./Examples/media/foo.png
• modelica:~//media/foo.png (empty relclass)

Further generalizations

As demonstrated by the forms above, these schemes can easily be extended with other ways of referring to a class by giving meaning to some new special content of the first path segments that cannot be mistaken for a (qualified) class name. For instance, a reference relative to the current top level class could be indicated by a '~~' (two '~') in the first path segment.

Class-relative resource

This section is divided into one subsection for each type of resource being referenced. Here, current class refers to the class referenced by the class part of the Modelica URI (not the class giving context to a relative class reference).

External resource

An external resource is a file stored in a structure reflecting the Modelica class hierarchy of the current class. The resource is specified using the resource query (the name is chosen to remind of the special directory name resources.d), for example:

• modelica:/Modelica/Electrical/Analog?resource=media/foo.png

For further details see, [resoruce-directory.md].

Class view

Different views of a class can be specified by using the view query:

• modelica:classref?view=diagram — Class diagram.
• modelica:classref?view=icon — Class icon.
  • Example: <img src="modelica:?view=icon" alt="class icon"/> (icon of the current class)
• modelica:classref?view=text — Textual class source code.
• modelica:classref?view=info — Class documentation. The fragment specifier can be used to reference a link anchor (present in the Documentation.info of the current class).
  • Example: modelica:/Modelica/Electrical/Analog?view=info#overview

Figure and plot

In the event that (MCP-0033) is accepted before this MCP, a figure is referenced using its identifier in the figure query.

• Example: modelica:/Modelica/Electrical/Analog/Examples/Rectifier?figure=voltcurr

To reference a plot inside a figure, one can also use the plot query (note that the plot identifier is only meaningful within a given figure).

• Example: modelica:/Modelica/Electrical/Analog/Examples/Rectifier?figure=voltcurr&plot=sumc1c2

Note that inheritance of figures means that the figure identifier is not necessarily referring to a figure defined in the current class, but could come from one of its parent classes.

While the example above was using the fullclass form of a Modelica URI, the most common place where a figure is references is probably in the documentation or other figures of the current class. Then, using a lookup-based form makes the class more self-contained.

• Example: modelica:?figure=voltcurr&plot=sumc1c2 (appearing in the Documentation.info of the current class)