Generalized Modelica URIs

RationaleMCP/0037/ReadMe.md

@@ -0,0 +1,53 @@
+# Modelica Change Proposal MCP-0037<br/>Generalized Modelica URIs
+Henrik Tidefelt
+
+**(In Development)**
+
+## Summary
+This MCP defines the next generation handling of external resources in Modelica.  The current forms of a Modelica URI have a problem with the case insensitivity of the _host_ part of the URI, so they need to be replaced one way or another.  This MCP takes the opportunity to combine a solution to the case insensitivity problem with a few other improvements to the Modelica URIs as well as handling of external resources more generally, see [below](#Rationale).
+
+## Revisions
+| Date | Description |
+| --- | --- |
+| 2020-07-22 | Henrik Tidefelt. Filling this document with initial content. |
+| 2023-03-23 | Henrik Tidefelt. Updates after design meeting discussions. |
+
+## Contributor License Agreement
+All authors of this MCP or their organizations have signed the "Modelica Contributor License Agreement".
+
+## Rationale
+This MCP consists of three parts:
+- `resolveURI` a new operator with function syntax to replace the MSL function `loadResource`, see [separate document](resolve-uri.md).
+- New forms of Modelica URIs, see [separate document](modelica-uris.md).
+- New structure for storing external resources with a Modelica class on a file system, see [separate document](resource-directory.md).
+
+See [#2387](https://github.com/modelica/ModelicaSpecification/pull/2387) for an extensive early discussion about the goals for this MCP.  Since then, the [MCP for figure annotations](https://github.com/modelica/ModelicaSpecification/pull/2482) has matured, adding new use cases for referencing resource within and across classes.
+
+Having `resolveURI` in the Modelica Language Specification instead of `loadResource` in the Modelica Standard Library is the natural place for the basic utility for dealing with a concept entirely defined in the Modelica Language Specification.  In addition, making it an operator with function syntax means we can use it to resolve Modelica URIs in ways that aren't possible with a normal function.
+
+Besides addressing the problem with case insensitivity of the _host_ part of a URI, the new forms are designed to address two major shortcomings of the current forms of Modelica URIs:
+- A class should be able to refer to its own resources without hard-coding its own fully qualified name.
+- References to special views of a class (_icon_, etc) shouldn't interfere with user-defined anchors and fragment specifiers.  Instead, Modelica URIs must have a flexible form allowing for new kinds of resources attached to a class, for example:
+  - Figures and plots.
+  - Figure style sheets (topic for future MCP).
+  - Named experiments (topic for future MCP).
+  - A component of the instantiated class.
+
+The file system storage of external resources together with a Modelica class makes use of a new, special, directory name for external resources, removing ambiguity in how to reference an external resource, as well as making it easier to determine which parts of a file system hierarchy that might contain external resources.
+
+## Backwards Compatibility
+Introducing the new operator with function syntax `resolveURI` means that Modelica code using this name for other purposes will break.  However, the name is unlikely to be in use in existing Modelica libraries.
+
+The new Modelica URIs are distinct from the existing Modelica URIs, making this part of the MCP fully backwards compatible.
+
+The new file system storage structure uses a directory name that couldn't be the name of a Modelica class.  Hence, the only kind of backwards incompatibility caused by this part of the MCP would be if a Modelica class is already using that name in the file hierarchy for something else.  Again, the name is unlikely to be used in existing Modelica libraries.
+
+## Tool Implementation
+
+### Experience with Prototype
+None yet.
+
+## Required Patents
+To the best of our knowledge, there are no patents that would conflict with the incorporation of this MCP.
+
+## References

RationaleMCP/0037/class-reference-separator.md

@@ -0,0 +1,52 @@
+# Class reference separator
+
+Two different choice of separator in Modelica URI class references have been considered, namely `/` and `.`.  The currently proposed separator in this MCP is `/`, while the legacy form of Modelica URIs use `.`.  This document gives reasons for and against the current proposal.
+
+
+## Reasons for using `.` (dot)
+
+Advantages of using `.` as separator in class references are given below.
+
+### Simple text editor copy/paste workflows
+
+Most class names using normal Modelica syntax can be directly copied and pasted to/from the class reference part of a Modelica URI.  (However this only works in most cases, not in general, see below.)
+
+### Possibility to use URI path to point out external resources
+
+The URI path could be used to specify a relative file path to an external resource of the class, just like in the legacy Modelica URI format:
+* _modelica:/Modelica.Electrical.Analog/media/foo.png_
+
+(Reasons are given below for why we shouldn't use this form of references to external resources anyway.)
+
+
+## Reasons for using `/` (slash)
+
+Now to the reasons behind `/` being the proposed separator after all.
+
+### The URI path should be used for external resource file paths anyway
+
+The external resources is only one of several kinds of resources referenced by Modelica URIs, and it makes sense to use the query part for all kinds instead of making an exception for external resources.
+
+### Splitting on `/` is part of standard URI handling
+
+Using `.` as separator would then mean a missed opportunity to use the split into path segments one gets for free from the general URI syntax when using `/` as separator.
+
+### URL encoding gives protection of `/`, not `.`
+
+There is also a technical detail speaking in the favor of `/` as separator, namely that URL encoding doesn't protect `.`, which means that the URI syntax can't be used to trivially split the class reference into its identifiers, needed to translate the class reference into a directory path.  Further, splitting the class references into its identifiers requires non-trivial string processing due to the potential presence of `.` inside single-quoted identifiers.  To illustrate, consider the Modelica class `MyPack.'A.B'.'C/D'`.  With `/` as separator and URL encoding of the path segments, one obtains:
+- _modelica:/MyPack/'A.B'/'C%2FD'_ — trivially split into its three (URL encoded) Modelica identifiers.
+With `.` as separator, on the other hand, one obtains:
+- _modelica:.MyPack.'A.B'.'C%2FD'_ — not so easily split into its three identifiers.
+
+### External resources with empty relative class reference
+
+In case one wants to point out external resources using the URI path, one also has to watch out for the pitfal of just leaving the _relclass_ empty when there are additional path segments:
+  * Wrong: _modelica://media?resource=foo.png_ (malformed, reminding of legacy form where _media_ would be the class reference)
+  * Wrong: _modelica:/media?resource=foo.png_ (fully qualified form — not the intention)
+  * Correct: _modelica:.//media?resource=foo.png_ (empty _relclass_; just a `.` cannot be mistaken for )
+
+### Modelica tools should support handling of Modelica URIs
+
+Many users will not be writing Modelica URIs by hand, but use a Modelica tool for creating the URI.  Among other, the tool should help with the URL encoding, and it is unlikely to matter much with separator it should produce, so it might as well be `/`.
+
+A Modelica tool can also provide functionality to copy the class reference of a Modelica URI in the form of a Modelica class name.  Compared to producing Modelica URIs from class names, however, this is probably a rarely needed feature.

RationaleMCP/0037/modelica-uris.md

@@ -0,0 +1,129 @@
+# 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](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier):
+```
+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 Modelica URIs described in this proposal have a mandatory _query_ part.  This makes them easily distinguishable from the legacy Modelica URI format, where the _query_ part of the URI is never used.
+
+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 `.`.
+
+An empty _authority_ is allowed as an alternative to not specifying the _authority_ at all.
+The use of a non-empty _authority_ is reserved for future use.  (It is also used in the legacy Modelica URI format.)
+
+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/…_ (no _query_ part, and possibly a non-empty _authority_) — This is the form defined today, referred to as the _legacy form_ (of a Modelica URI) as of this MCP.
+  * 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](resolve-uri.md), also introduced by this MCP.
+
+A [separate rationale](relative-class-references.md) 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 work 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](class-reference-separator.md) 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_](resource-directory.md)), for example:
+- _modelica:/Modelica/Electrical/Analog?resource=media/foo.png_
+
+For further details see, [resource-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 an element by `id` or `name` (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](https://github.com/modelica/ModelicaSpecification/pull/2482)) 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_
+
+In the context of a `Figure`, a `Plot` is uniquely identified by its `identifier`.  One way to reference a plot would therefore be to append a `plot` query:
+  * Example: _modelica:/Modelica/Electrical/Analog/Examples/Rectifier?figure=voltcurr&plot=sumc1c2_
+
+However, a more useful way to reference a plot is to make use of the fragmet specifier, which naturally applies to anything with an `identifier` inside the referenced figure:
+  * Example: _modelica:/Modelica/Electrical/Analog/Examples/Rectifier?figure=voltcurr#sumc1c2_
+
+ By using the fragment specifier instead of the `plot` query, it becomes possible to use a URI which is relative to the current figure.  This is useful when referencing a plot from the `caption` of a `Figure` (replacing the old way `caption = "%(plot:sumc1c2) Sum of two connectors."`, where `plot` isn't really a URI scheme, and the `Plot` identifier `sumc1c2` isn't URL encoded):
+   * Example: `caption = "%(#sumc1c2) Sum of two connectors."` (thanks to URL encoding, this also works for nasty identifiers containing parentheses)
+
+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#sumc1c2_ (appearing in the `Documentation.info` of the current class)