From 21cab6a350a966fc10b4f200605fe3655dbd788d Mon Sep 17 00:00:00 2001 From: Henrik Tidefelt Date: Mon, 10 Aug 2020 23:19:52 +0200 Subject: [PATCH 01/29] Initial commit of files for MCP-0037 based on first comment of #2387 This is just the starting point. In the following commits, later comments of #2387 will be considered and possibly incorporated. --- RationaleMCP/0037/ReadMe.md | 51 +++++++++++++++++++++++++ RationaleMCP/0037/modelica-uris.md | 6 +++ RationaleMCP/0037/resolve-uri.md | 5 +++ RationaleMCP/0037/resource-directory.md | 5 +++ 4 files changed, 67 insertions(+) create mode 100644 RationaleMCP/0037/ReadMe.md create mode 100644 RationaleMCP/0037/modelica-uris.md create mode 100644 RationaleMCP/0037/resolve-uri.md create mode 100644 RationaleMCP/0037/resource-directory.md diff --git a/RationaleMCP/0037/ReadMe.md b/RationaleMCP/0037/ReadMe.md new file mode 100644 index 000000000..8534db66e --- /dev/null +++ b/RationaleMCP/0037/ReadMe.md @@ -0,0 +1,51 @@ +# Modelica Change Proposal MCP-0037
Generalized Modelica URIs for external resources +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. | + +## 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 [#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 Stanard 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 ([MCP-0033](https://github.com/modelica/ModelicaSpecification/pull/2482)). + - Figure style sheets (topic for future MCP). + - Reference result of an `experiment` annotation (topic for future MCP). + +The file system storage of external resources together with a Modelica class makes use of a new, special, directory name for external resources, removing amiguity 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. However, the existing Modelica URIs will become a deprecated form according to this MCP. + +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 diff --git a/RationaleMCP/0037/modelica-uris.md b/RationaleMCP/0037/modelica-uris.md new file mode 100644 index 000000000..8a72b61b9 --- /dev/null +++ b/RationaleMCP/0037/modelica-uris.md @@ -0,0 +1,6 @@ +# Modelica URIs + +The modelica URI format is extended to allow the following forms (examples and more details were included in the old email thread, and might be of interest to also include here): +- _"modelica://host/relpath"_ (non-empty host) — This is the form defined today, and should probably be deprecated. +- _"modelica:///~/relpath"_ — This is a reference to the current top level package. This is useful for organizing all resources in a hierarchy which is separate from the package hierarchy, like the current MSL. +- _"modelica:///{../}class/relpath"_ (that is, zero or more occurrences of _"../"_ followed by a classname that may be fully qualified) — Starting from the current scope, each _"../"_ moves one level up the class tree. From that location in the class tree, the class is resolved using normal lookup. A special and important case is to leave class empty, meaning a reference to the class where the lookup starts. The lookup-based rule is useful for organizing external resources with a close coupling to the classes that use them. diff --git a/RationaleMCP/0037/resolve-uri.md b/RationaleMCP/0037/resolve-uri.md new file mode 100644 index 000000000..f49cdcb4e --- /dev/null +++ b/RationaleMCP/0037/resolve-uri.md @@ -0,0 +1,5 @@ +# The resolveURI operator + +An operator with function syntax called `resolveURI` is introduced. Unlike a normal function, it knows about its call site, so that it can apply normal lookup rules. It would make sense to standardize on either of the following two variants: +- It only operates on constant strings. This way, application of lookup rules doesn't require a runtime representation of the class tree. +- It only evaluates at runtime, allowing a built simulation to be transferred from one tool installation to another. diff --git a/RationaleMCP/0037/resource-directory.md b/RationaleMCP/0037/resource-directory.md new file mode 100644 index 000000000..d5f384793 --- /dev/null +++ b/RationaleMCP/0037/resource-directory.md @@ -0,0 +1,5 @@ +# The _package-resources_ directory + +When mapping the forms with empty host to a resource location, each identifier of the fully qualified class name is mapped to a subdirectory level of the external resource hierarchy (in the same way as the old form with host), where the _relpath_ is resolved within the directory _package-resources_ (alternatively _resources.d_). + +Unlike the old form with host, there is no restriction on the first part of _relpath_. However, in the same spirit, the _relpath_ is not allowed to reference anything outside the _package-resources_ directory, so that the only way a Modelica URI can reference a resource is by referencing the class to which the _package-resources_ directory belongs. From 351331b2b9dfdf2350ff05514a22f8bdbdc38db3 Mon Sep 17 00:00:00 2001 From: Henrik Tidefelt Date: Mon, 17 Aug 2020 00:34:55 +0200 Subject: [PATCH 02/29] Extend description of Modelica URI forms --- RationaleMCP/0037/ReadMe.md | 5 ++- RationaleMCP/0037/modelica-uris.md | 72 ++++++++++++++++++++++++++++-- 2 files changed, 71 insertions(+), 6 deletions(-) diff --git a/RationaleMCP/0037/ReadMe.md b/RationaleMCP/0037/ReadMe.md index 8534db66e..0099adc8c 100644 --- a/RationaleMCP/0037/ReadMe.md +++ b/RationaleMCP/0037/ReadMe.md @@ -18,7 +18,7 @@ All authors of this MCP or their organizations have signed the "Modelica Contrib 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. +- 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. @@ -29,7 +29,8 @@ Besides addressing the problem with case insensitivity of the _host_ part of a U - 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 ([MCP-0033](https://github.com/modelica/ModelicaSpecification/pull/2482)). - Figure style sheets (topic for future MCP). - - Reference result of an `experiment` annotation (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 amiguity 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. diff --git a/RationaleMCP/0037/modelica-uris.md b/RationaleMCP/0037/modelica-uris.md index 8a72b61b9..b50e1eda3 100644 --- a/RationaleMCP/0037/modelica-uris.md +++ b/RationaleMCP/0037/modelica-uris.md @@ -1,6 +1,70 @@ # Modelica URIs -The modelica URI format is extended to allow the following forms (examples and more details were included in the old email thread, and might be of interest to also include here): -- _"modelica://host/relpath"_ (non-empty host) — This is the form defined today, and should probably be deprecated. -- _"modelica:///~/relpath"_ — This is a reference to the current top level package. This is useful for organizing all resources in a hierarchy which is separate from the package hierarchy, like the current MSL. -- _"modelica:///{../}class/relpath"_ (that is, zero or more occurrences of _"../"_ followed by a classname that may be fully qualified) — Starting from the current scope, each _"../"_ moves one level up the class tree. From that location in the class tree, the class is resolved using normal lookup. A special and important case is to leave class empty, meaning a reference to the class where the lookup starts. The lookup-based rule is useful for organizing external resources with a close coupling to the classes that use them. +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.) + +A Modelica URI can be divided into two main parts: a reference to a Modelica class, followed by a resource specified relative to the class. In terms of generic URI syntax, the class reference is given by the first part of the URI's _path_ — except for the current Modelica URIs, where the class reference is given by the _host_ part (occupying the entire _autority_). A varying number of path segments are used to specify the class, but one can always immediately tell where the class reference part ends and where the class-relative resource part begins. + +## Class reference +Below, "…" represent the class-relative resource part of the Modelica URI, [described below](class-relative-resource). These are the different ways of referencing a class, where the _host_, _fullclass_, and _relclass_ represent a Modelica class reference (that is, Modelica identifiers, separated by the period charater, and hence free of the path separator that would have to be percent-encoded if present inside a quoted identifier): +- _modelica://host/…_ (non-empty host) — This is the form defined today, becoming deprecated as of this MCP. + * Example: _modelica://Modelica.Electrical.Analog/media/foo.png_ +- _modelica:///fullclass…_ — Class given by its fully qualified name, without leading period. + * Example: _modelica:///Modelica.Electrical.Analog/media/foo.png_ +- _modelica:///./relclass…_ — Class given by lookup of _relclass_ in the class tree — requires class tree context. + * Example: _modelica:///./Examples/media/foo.png_ + * Example: _modelica:///.//media/foo.png_ (empty _relclass_) + * Example: _modelica:///.?figure=Disturbances&plot=Wind_ (empty _relclass_) +- _modelica:///~/relclass…_ — This is a reference with class lookup 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:///~//media/foo.png_ (empty _relclass_) + * Example: _modelica:///~/Documentation?view=info#introduction_ + +As demonstrated by the forms above, this scheme can easily be extended with other ways of referring to a class by giving meaning to some new special content of the first path segment that cannot be mistaken for a _fullclass_. + +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). + +Note that the lookup-based forms can only be used in a context where a class tree context is given. It is an error if _relclass_ doesn't resolve to a class within the same top level package as that of the lookup context — references to resources in a different top level package must use the fully qualified form. This context can be given in one of two ways: +- A string literal 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 be able to perform lookup. 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. + +## 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 rest of the URI path part, for example: +- _modelica:///Modelica.Electrical.Analog/media/foo.png_ + +Here, the _media/foo.png_ is a relative file system path that is resolved within a resource directory associated with the current class. The details of this mapping for the deprecated _host_ form of a Modelica URI are omitted here; the following only applies to the non-deprecated forms, when the current Modelica package is stored in a file system hierarchy: +- The fully qualified class name (after resolving any _relclass_ with respect to the class tree context) is mapped to a nested directory structure, with the constant directory name _resources.d_ (alternatively _package-resources_) appended. +- The relative file system path is relative to _resources.d_ and may not resolve to a location outside _resources.d_. + +In the example Modelica URI above, assume `Modelica` is stored in _/Users/jdoe/modelica-packages/Modelica-4.0/Modelica_. Then, the resolved external resource is: +- _/Users/jdoe/modelica-packages/Modelica-4.0/Modelica/Electrical/Analog/resources.d/media/foo.png_ + +Note that the mapping of the fully qualified class name to a directory is the same regardless of whether the package itself uses a directory hierarchy for storage — the directory hierarchy for external resoruces is fixed, and it is only one of several options for the package itself to be stored in the same hierarchy. + +### 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: `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](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_ + +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) + +**It would be great if the path could be omitted with it's just a period.** From 088abe76e08edea34f4138651ab21b869198b9a6 Mon Sep 17 00:00:00 2001 From: Henrik Tidefelt Date: Tue, 18 Aug 2020 00:26:50 +0200 Subject: [PATCH 03/29] Elaborate on external resource handling and resolveURI --- RationaleMCP/0037/modelica-uris.md | 17 ++++------- RationaleMCP/0037/resolve-uri.md | 40 +++++++++++++++++++++++-- RationaleMCP/0037/resource-directory.md | 16 ++++++++-- 3 files changed, 57 insertions(+), 16 deletions(-) diff --git a/RationaleMCP/0037/modelica-uris.md b/RationaleMCP/0037/modelica-uris.md index b50e1eda3..bd51b92dc 100644 --- a/RationaleMCP/0037/modelica-uris.md +++ b/RationaleMCP/0037/modelica-uris.md @@ -8,13 +8,13 @@ A Modelica URI can be divided into two main parts: a reference to a Modelica cla Below, "…" represent the class-relative resource part of the Modelica URI, [described below](class-relative-resource). These are the different ways of referencing a class, where the _host_, _fullclass_, and _relclass_ represent a Modelica class reference (that is, Modelica identifiers, separated by the period charater, and hence free of the path separator that would have to be percent-encoded if present inside a quoted identifier): - _modelica://host/…_ (non-empty host) — This is the form defined today, becoming deprecated as of this MCP. * Example: _modelica://Modelica.Electrical.Analog/media/foo.png_ -- _modelica:///fullclass…_ — Class given by its fully qualified name, without leading period. +- _modelica:///fullclass…_ — Class given by its fully qualified name, without leading period. It is an error if _fullclass_ does not refer to an existing class. * Example: _modelica:///Modelica.Electrical.Analog/media/foo.png_ -- _modelica:///./relclass…_ — Class given by lookup of _relclass_ in the class tree — requires class tree context. +- _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/media/foo.png_ * Example: _modelica:///.//media/foo.png_ (empty _relclass_) * Example: _modelica:///.?figure=Disturbances&plot=Wind_ (empty _relclass_) -- _modelica:///~/relclass…_ — This is a reference with class lookup 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. +- _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:///~//media/foo.png_ (empty _relclass_) * Example: _modelica:///~/Documentation?view=info#introduction_ @@ -35,14 +35,7 @@ This section is divided into one subsection for each type of resource being refe 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 rest of the URI path part, for example: - _modelica:///Modelica.Electrical.Analog/media/foo.png_ -Here, the _media/foo.png_ is a relative file system path that is resolved within a resource directory associated with the current class. The details of this mapping for the deprecated _host_ form of a Modelica URI are omitted here; the following only applies to the non-deprecated forms, when the current Modelica package is stored in a file system hierarchy: -- The fully qualified class name (after resolving any _relclass_ with respect to the class tree context) is mapped to a nested directory structure, with the constant directory name _resources.d_ (alternatively _package-resources_) appended. -- The relative file system path is relative to _resources.d_ and may not resolve to a location outside _resources.d_. - -In the example Modelica URI above, assume `Modelica` is stored in _/Users/jdoe/modelica-packages/Modelica-4.0/Modelica_. Then, the resolved external resource is: -- _/Users/jdoe/modelica-packages/Modelica-4.0/Modelica/Electrical/Analog/resources.d/media/foo.png_ - -Note that the mapping of the fully qualified class name to a directory is the same regardless of whether the package itself uses a directory hierarchy for storage — the directory hierarchy for external resoruces is fixed, and it is only one of several options for the package itself to be stored in the same hierarchy. +This is currently the only form of (non-deprecated) Modelica URI with a path that continues after the class reference part, and this form is currently not combined with neither a query or a fragment specifier. For further details see, [resoruce-directory.md]. ### Class view @@ -67,4 +60,4 @@ Note that inheritance of figures means that the `figure` identifier is not neces 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) -**It would be great if the path could be omitted with it's just a period.** +**It would be great if the path could be omitted when it's just a period.** diff --git a/RationaleMCP/0037/resolve-uri.md b/RationaleMCP/0037/resolve-uri.md index f49cdcb4e..e88347169 100644 --- a/RationaleMCP/0037/resolve-uri.md +++ b/RationaleMCP/0037/resolve-uri.md @@ -1,5 +1,41 @@ # The resolveURI operator -An operator with function syntax called `resolveURI` is introduced. Unlike a normal function, it knows about its call site, so that it can apply normal lookup rules. It would make sense to standardize on either of the following two variants: -- It only operates on constant strings. This way, application of lookup rules doesn't require a runtime representation of the class tree. +An operator with function syntax called `resolveURI` is introduced. Compared to `loadResource`, it is more powerful, will have more clearly defined semantics, and is properly defined as Modelica lanugage feature instead of bypassing the Modelica Language Specification by means of `ModelicaServices`. + +The result of `resolveURI(uri)` is a `String` giving the absolute filename of the external resource referenced by `uri`. Unlike a normal function, it knows about its call site, so that it can apply normal lookup rules. + +`resolveURI` accepts two kinds of URIs: +- _file:///…_ — only allowing absolute _file_ URIs +- _modelica:///…_ — any Modelica URI except the deprecated _host_ form + +The reason that relative file URIs are not supported by `resolveURI` is that the base URI would most naturally be the file in which the Modelica source code of the `resolveURI` expression is stored, but a Modelica tool is not required to store classes in a file system, so this also encourages the use of Modelica URIs to handle resources attached to a Modelica class. + +For a Modelica URI, `resolveURI` provides a context for lookup-based Modelica URIs, namely the class containing the `resolveURI` expression. The following example illustrates how `resolveURI` gives context to a lookup-based URI: +``` +package P + model M + model A + end A; + constant String uri; + String filename = resolveURI(uri); + end M; + + model A + end A; + + M m(uri = "modelica:///./A/table.mat"); +end P; +``` +Here, the lookup of `uri` doesn't take place where the string literal appears (namely `P`, which would have resulted in _…/P/A/resources.d/table.mat_). Instead, the lookup happens in the context `P.M`, resulting in `m.filename` being _…/P/M/A/resources.d/table.mat_. + +The example above may seem counter-intuitive, but the example is contrived and the potential confusion is typically avoided by applying `resolveURI` directly to a string literal; then the context of the string literal coincides with the context given by the `resolveURI` expression. + +Note that a `resolveURI` expression is an expression resulting in an absolute filename, and shall not be used where a URI is expected (as in the `src` of an `img` tag in the `Documentation` annotation). + +## Evaluation semantics + +It would make sense to standardize on either of the following two variants: +- It only operates on constant strings. This way, application of lookup rules doesn't require a runtime representation of the class tree. - It only evaluates at runtime, allowing a built simulation to be transferred from one tool installation to another. + +A clear drawback of runtime evaluation is that it becomes impossible to make external resources part of a `constant` expression — the variability of a `resolveURI` expression would be no less than `parameter`. diff --git a/RationaleMCP/0037/resource-directory.md b/RationaleMCP/0037/resource-directory.md index d5f384793..f5a591920 100644 --- a/RationaleMCP/0037/resource-directory.md +++ b/RationaleMCP/0037/resource-directory.md @@ -1,5 +1,17 @@ # The _package-resources_ directory -When mapping the forms with empty host to a resource location, each identifier of the fully qualified class name is mapped to a subdirectory level of the external resource hierarchy (in the same way as the old form with host), where the _relpath_ is resolved within the directory _package-resources_ (alternatively _resources.d_). +Consider the following reference to an external resource: +- _modelica:///Modelica.Electrical.Analog/media/foo.png_ -Unlike the old form with host, there is no restriction on the first part of _relpath_. However, in the same spirit, the _relpath_ is not allowed to reference anything outside the _package-resources_ directory, so that the only way a Modelica URI can reference a resource is by referencing the class to which the _package-resources_ directory belongs. +The part before _/media/foo.png_ is the class reference, and could take different forms, as described in [modelica-uris.md]. The referenced class is denoted _current class_, here `Modelica.Electrical.Analog`. + +Here, the _media/foo.png_ is a relative file system path that is resolved within a resource directory associated with the current class. The details of this mapping for the deprecated _host_ form of a Modelica URI are omitted here; the following only applies to the non-deprecated forms, when the current Modelica package is stored in a file system hierarchy: +- The fully qualified class name of the current class (after resolving any _relclass_ with respect to the class tree context) is mapped to a nested directory structure, with the constant directory name _resources.d_ (alternatively _package-resources_) appended. +- The relative file system path is relative to _resources.d_ and may not contain the special path segments "." or "..". + +Note that the period (".") in the name _resources.d_ makes it distinguishable from a Modelica identifier. In combination with the constraints on the relative file system path, this implies that that the referenced resourse resides inside the _resources.d_ directory of the class, and that any Modelica URI referencing this resource must do so via reference to the current class. + +In the example Modelica URI above, assume `Modelica` is stored in _/Users/jdoe/modelica-packages/Modelica-4.3.2/Modelica_. Then, the resolved external resource is: +- _/Users/jdoe/modelica-packages/Modelica-4.3.2/Modelica/Electrical/Analog/resources.d/media/foo.png_ + +Note that the mapping of the fully qualified class name to a directory is the same regardless of whether the package itself uses a directory hierarchy for storage — the directory hierarchy for external resoruces is fixed, and it is only one of several options for the package itself to be stored in the same hierarchy. From a848435e591f727fb1e712b8a3d79eee4cd9fcee Mon Sep 17 00:00:00 2001 From: Henrik Tidefelt Date: Thu, 20 Aug 2020 22:37:21 +0200 Subject: [PATCH 04/29] Alternative approaches to the class reference --- RationaleMCP/0037/modelica-uris.md | 77 +++++++++++++++++++++++++++--- 1 file changed, 70 insertions(+), 7 deletions(-) diff --git a/RationaleMCP/0037/modelica-uris.md b/RationaleMCP/0037/modelica-uris.md index bd51b92dc..1631528f7 100644 --- a/RationaleMCP/0037/modelica-uris.md +++ b/RationaleMCP/0037/modelica-uris.md @@ -5,9 +5,25 @@ The Modelica URI format is extended to give meaning to the forms described below A Modelica URI can be divided into two main parts: a reference to a Modelica class, followed by a resource specified relative to the class. In terms of generic URI syntax, the class reference is given by the first part of the URI's _path_ — except for the current Modelica URIs, where the class reference is given by the _host_ part (occupying the entire _autority_). A varying number of path segments are used to specify the class, but one can always immediately tell where the class reference part ends and where the class-relative resource part begins. ## Class reference -Below, "…" represent the class-relative resource part of the Modelica URI, [described below](class-relative-resource). These are the different ways of referencing a class, where the _host_, _fullclass_, and _relclass_ represent a Modelica class reference (that is, Modelica identifiers, separated by the period charater, and hence free of the path separator that would have to be percent-encoded if present inside a quoted identifier): -- _modelica://host/…_ (non-empty host) — This is the form defined today, becoming deprecated as of this MCP. + +This section presents a couple of alternative designs, meant to be discussed in the language group before deciding which one to proceed with. + +Below, "…" represent the class-relative resource part of the Modelica URI, [described below](class-relative-resource). + +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_ + +### Modelica URI 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. + + +### Base proposal: Empty authority, dot-separation, and Modelica lookup + +These are the different ways of referencing a class, where the _host_, _fullclass_, and _relclass_ represent a Modelica class reference (that is, Modelica identifiers, separated by the period ("dot") charater, and hence free of the path separator that would have to be percent-encoded if present inside a quoted identifier): - _modelica:///fullclass…_ — Class given by its fully qualified name, without leading period. It is an error if _fullclass_ does not refer to an existing class. * Example: _modelica:///Modelica.Electrical.Analog/media/foo.png_ - _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. @@ -18,13 +34,60 @@ Below, "…" represent the class-relative resource part of the Modelica URI, [de * Example: _modelica:///~//media/foo.png_ (empty _relclass_) * Example: _modelica:///~/Documentation?view=info#introduction_ -As demonstrated by the forms above, this scheme can easily be extended with other ways of referring to a class by giving meaning to some new special content of the first path segment that cannot be mistaken for a _fullclass_. - 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). -Note that the lookup-based forms can only be used in a context where a class tree context is given. It is an error if _relclass_ doesn't resolve to a class within the same top level package as that of the lookup context — references to resources in a different top level package must use the fully qualified form. This context can be given in one of two ways: -- A string literal 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 be able to perform lookup. 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. +### 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 + +Here is another idea from the early discussions on how to form the new Modelica URIs. + +The special meaning given to the path segments '.' and '..' is clearly inspired by file paths, but with the difference that the class references presented above use the standard '.' to separate identifiers in the qualified class name of the Modelica URI. The analogy with file paths would be even better if the qualified class name in the Modelica URI used '/' as separator. + +This then require a different way of giving a relative file path after the class reference, because there would be no easy way of telling where the class reference ends in an example like this: + * Bad: _modelica:///Modelica/Electrical/Analog/media/foo.png_ + +It could be solved with some URI abuse, where a special character inside a segment marks the split (note that the split doesn't correspond to normal URI parsing): + * URI abuse: _modelica:///Modelica/Electrical/Analog:media/foo.png_ + +Using a query becomes a bit more verbose, but seems pretty safe otherwise (using the name _resource_ in the query to connect with the special directory name [_resources.d_](resource-directory.md)): + * Query solution: _modelica:///Modelica/Electrical/Analog?resource=media/foo.png_ + +### Modelica URIs without authority + +In the (non-deprecated) Modelica URI forms above, the authority part of the URI was always empty, causing the cumbersome sequence `:///` separating the URI scheme from the class reference. By omitting the authority instead of leaving it empty, the Modelica URIs become more readable. + +Examples: + * Fully qualified: _modelica:Modelica.Electrical.Analog/media/foo.png_ + * Lookup-based: _modelica:./Examples/media/foo.png_ + * Lookup-based: _modelica:.//media/foo.png_ (empty _relclass_) + * Lookup-based: _modelica:.?figure=Disturbances&plot=Wind_ (empty _relclass_) + * Lookup-based: _modelica:~//media/foo.png_ (empty _relclass_) + * Lookup-based: _modelica:~/Documentation?view=info#introduction_ + + While it double be tempting to require a leading '/' to indicate a fully qualified class reference and allow the leading `.` segment to be omitted, + * Fully qualified: _modelica:/Modelica.Electrical.Analog/media/foo.png_ + * Lookup-based: _modelica:Examples/media/foo.png_ + * Lookup-based: _modelica:?figure=Disturbances&plot=Wind_ (empty _relclass_) + +one would have to watch out for the pitfal of just leaving the _relclass_ empty when there are additional path segments: + * Wrong: _modelica://media/foo.png_ (deprecated form where _media_ would be the class reference) + * Wrong: _modelica:/media/foo.png_ (fully qualified form — not the intention) + * Correct: _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 From 115a9e2207367eaa9803271a7e340cbc3a2e03f9 Mon Sep 17 00:00:00 2001 From: Henrik Tidefelt Date: Tue, 15 Sep 2020 01:02:42 +0200 Subject: [PATCH 05/29] Improved proposal based on general structure of URIs --- RationaleMCP/0037/modelica-uris.md | 108 ++++++++++-------------- RationaleMCP/0037/resolve-uri.md | 4 +- RationaleMCP/0037/resource-directory.md | 4 +- 3 files changed, 50 insertions(+), 66 deletions(-) diff --git a/RationaleMCP/0037/modelica-uris.md b/RationaleMCP/0037/modelica-uris.md index 1631528f7..e1f59c51a 100644 --- a/RationaleMCP/0037/modelica-uris.md +++ b/RationaleMCP/0037/modelica-uris.md @@ -2,14 +2,19 @@ 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.) -A Modelica URI can be divided into two main parts: a reference to a Modelica class, followed by a resource specified relative to the class. In terms of generic URI syntax, the class reference is given by the first part of the URI's _path_ — except for the current Modelica URIs, where the class reference is given by the _host_ part (occupying the entire _autority_). A varying number of path segments are used to specify the class, but one can always immediately tell where the class reference part ends and where the class-relative resource part begins. +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] +``` + +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 not defined except for in the deprecated form of a Modelica URI. A tool should be able to interpret Modelica URIs both without _authority_ and with an empty _authority_. When _authority_ is present, any `/` separator following the _authority_ is just the separator between the _authority_ and the class reference, and not part of the class reference. ## 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. -Below, "…" represent the class-relative resource part of the Modelica URI, [described below](class-relative-resource). - 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_ @@ -21,18 +26,22 @@ Among the proposed forms of class references below, there are some that are only - The [`resolveURI` operator](resolve-uri.md), also introduced by this MCP. -### Base proposal: Empty authority, dot-separation, and Modelica lookup +### 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 Modelica class reference (that is, Modelica identifiers, separated by the period ("dot") charater, and hence free of the path separator that would have to be percent-encoded if present inside a quoted identifier): -- _modelica:///fullclass…_ — Class given by its fully qualified name, without leading period. It is an error if _fullclass_ does not refer to an existing class. - * Example: _modelica:///Modelica.Electrical.Analog/media/foo.png_ -- _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/media/foo.png_ - * Example: _modelica:///.//media/foo.png_ (empty _relclass_) - * Example: _modelica:///.?figure=Disturbances&plot=Wind_ (empty _relclass_) -- _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:///~//media/foo.png_ (empty _relclass_) - * Example: _modelica:///~/Documentation?view=info#introduction_ +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_ +- _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:._ (empty _relclass_) + * Example: _modelica:///._ (empty _relclass_ with _authority_ present) +- _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). @@ -43,44 +52,21 @@ While powerful and tightly coupled with the rest of the Modelica language, the l - 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 - -Here is another idea from the early discussions on how to form the new Modelica URIs. - -The special meaning given to the path segments '.' and '..' is clearly inspired by file paths, but with the difference that the class references presented above use the standard '.' to separate identifiers in the qualified class name of the Modelica URI. The analogy with file paths would be even better if the qualified class name in the Modelica URI used '/' as separator. +- _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_ -This then require a different way of giving a relative file path after the class reference, because there would be no easy way of telling where the class reference ends in an example like this: - * Bad: _modelica:///Modelica/Electrical/Analog/media/foo.png_ +### Class references with '.' separator -It could be solved with some URI abuse, where a special character inside a segment marks the split (note that the split doesn't correspond to normal URI parsing): - * URI abuse: _modelica:///Modelica/Electrical/Analog:media/foo.png_ +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 `/`. The advantage of doing this is that the URI path can then also be used to specify a relative file path to an external resource of the class, just like in the old Modelica URI format: +* _modelica:/Modelica.Electrical.Analog/media/foo.png_ -Using a query becomes a bit more verbose, but seems pretty safe otherwise (using the name _resource_ in the query to connect with the special directory name [_resources.d_](resource-directory.md)): - * Query solution: _modelica:///Modelica/Electrical/Analog?resource=media/foo.png_ +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_) -### Modelica URIs without authority - -In the (non-deprecated) Modelica URI forms above, the authority part of the URI was always empty, causing the cumbersome sequence `:///` separating the URI scheme from the class reference. By omitting the authority instead of leaving it empty, the Modelica URIs become more readable. - -Examples: - * Fully qualified: _modelica:Modelica.Electrical.Analog/media/foo.png_ - * Lookup-based: _modelica:./Examples/media/foo.png_ - * Lookup-based: _modelica:.//media/foo.png_ (empty _relclass_) - * Lookup-based: _modelica:.?figure=Disturbances&plot=Wind_ (empty _relclass_) - * Lookup-based: _modelica:~//media/foo.png_ (empty _relclass_) - * Lookup-based: _modelica:~/Documentation?view=info#introduction_ - - While it double be tempting to require a leading '/' to indicate a fully qualified class reference and allow the leading `.` segment to be omitted, - * Fully qualified: _modelica:/Modelica.Electrical.Analog/media/foo.png_ - * Lookup-based: _modelica:Examples/media/foo.png_ - * Lookup-based: _modelica:?figure=Disturbances&plot=Wind_ (empty _relclass_) - -one would have to watch out for the pitfal of just leaving the _relclass_ empty when there are additional path segments: +One has to watch out for the pitfal of just leaving the _relclass_ empty when there are additional path segments: * Wrong: _modelica://media/foo.png_ (deprecated form where _media_ would be the class reference) * Wrong: _modelica:/media/foo.png_ (fully qualified form — not the intention) * Correct: _modelica:.//media/foo.png_ (empty _relclass_) @@ -95,32 +81,30 @@ This section is divided into one subsection for each type of resource being refe ### 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 rest of the URI path part, for example: -- _modelica:///Modelica.Electrical.Analog/media/foo.png_ +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_ -This is currently the only form of (non-deprecated) Modelica URI with a path that continues after the class reference part, and this form is currently not combined with neither a query or a fragment specifier. For further details see, [resoruce-directory.md]. +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: `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_ +- _modelica:classref?view=diagram_ — Class diagram. +- _modelica:classref?view=icon_ — Class icon. + * Example: `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](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_ + * 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_ + * 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) - -**It would be great if the path could be omitted when it's just a period.** + * Example: _modelica:?figure=voltcurr&plot=sumc1c2_ (appearing in the `Documentation.info` of the current class) diff --git a/RationaleMCP/0037/resolve-uri.md b/RationaleMCP/0037/resolve-uri.md index e88347169..db10586ec 100644 --- a/RationaleMCP/0037/resolve-uri.md +++ b/RationaleMCP/0037/resolve-uri.md @@ -6,7 +6,7 @@ The result of `resolveURI(uri)` is a `String` giving the absolute filename of th `resolveURI` accepts two kinds of URIs: - _file:///…_ — only allowing absolute _file_ URIs -- _modelica:///…_ — any Modelica URI except the deprecated _host_ form +- _modelica:…_ — any Modelica URI except the deprecated _host_ form The reason that relative file URIs are not supported by `resolveURI` is that the base URI would most naturally be the file in which the Modelica source code of the `resolveURI` expression is stored, but a Modelica tool is not required to store classes in a file system, so this also encourages the use of Modelica URIs to handle resources attached to a Modelica class. @@ -23,7 +23,7 @@ package P model A end A; - M m(uri = "modelica:///./A/table.mat"); + M m(uri = "modelica:A?resource=table.mat"); end P; ``` Here, the lookup of `uri` doesn't take place where the string literal appears (namely `P`, which would have resulted in _…/P/A/resources.d/table.mat_). Instead, the lookup happens in the context `P.M`, resulting in `m.filename` being _…/P/M/A/resources.d/table.mat_. diff --git a/RationaleMCP/0037/resource-directory.md b/RationaleMCP/0037/resource-directory.md index f5a591920..0e4e7a773 100644 --- a/RationaleMCP/0037/resource-directory.md +++ b/RationaleMCP/0037/resource-directory.md @@ -1,9 +1,9 @@ # The _package-resources_ directory Consider the following reference to an external resource: -- _modelica:///Modelica.Electrical.Analog/media/foo.png_ +- _modelica:/Modelica/Electrical/Analog?resource=media/foo.png_ -The part before _/media/foo.png_ is the class reference, and could take different forms, as described in [modelica-uris.md]. The referenced class is denoted _current class_, here `Modelica.Electrical.Analog`. +The URI path part is the class reference, and could take different forms, as described in [modelica-uris.md]. The referenced class is denoted _current class_, here `Modelica.Electrical.Analog`. Here, the _media/foo.png_ is a relative file system path that is resolved within a resource directory associated with the current class. The details of this mapping for the deprecated _host_ form of a Modelica URI are omitted here; the following only applies to the non-deprecated forms, when the current Modelica package is stored in a file system hierarchy: - The fully qualified class name of the current class (after resolving any _relclass_ with respect to the class tree context) is mapped to a nested directory structure, with the constant directory name _resources.d_ (alternatively _package-resources_) appended. From 6ac6a64db563139e3a659bfd8b9bd873d213f037 Mon Sep 17 00:00:00 2001 From: Henrik Tidefelt Date: Tue, 15 Sep 2020 01:07:28 +0200 Subject: [PATCH 06/29] Remove too restrictive 'for external resources' from MCP name --- RationaleMCP/0037/ReadMe.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/RationaleMCP/0037/ReadMe.md b/RationaleMCP/0037/ReadMe.md index 0099adc8c..1cc1392c0 100644 --- a/RationaleMCP/0037/ReadMe.md +++ b/RationaleMCP/0037/ReadMe.md @@ -1,4 +1,4 @@ -# Modelica Change Proposal MCP-0037
Generalized Modelica URIs for external resources +# Modelica Change Proposal MCP-0037
Generalized Modelica URIs Henrik Tidefelt **(In Development)** From ac91be6d82a9769e9e23cac4c5d54f543e56033b Mon Sep 17 00:00:00 2001 From: Henrik Tidefelt Date: Tue, 15 Sep 2020 08:02:50 +0200 Subject: [PATCH 07/29] Recommend trying an online tool for general URI parsing --- RationaleMCP/0037/modelica-uris.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/RationaleMCP/0037/modelica-uris.md b/RationaleMCP/0037/modelica-uris.md index e1f59c51a..5bd9cac20 100644 --- a/RationaleMCP/0037/modelica-uris.md +++ b/RationaleMCP/0037/modelica-uris.md @@ -7,6 +7,8 @@ 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 + 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 not defined except for in the deprecated form of a Modelica URI. A tool should be able to interpret Modelica URIs both without _authority_ and with an empty _authority_. When _authority_ is present, any `/` separator following the _authority_ is just the separator between the _authority_ and the class reference, and not part of the class reference. From 24a5404745aec620d7d15ef24266b1139f7f29f0 Mon Sep 17 00:00:00 2001 From: Henrik Tidefelt Date: Tue, 15 Sep 2020 08:04:14 +0200 Subject: [PATCH 08/29] Remove exception for Modelica URIs with authority Even if empty, the presence of the URI authority part forces the class reference into the 'absclass' form. --- RationaleMCP/0037/modelica-uris.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/RationaleMCP/0037/modelica-uris.md b/RationaleMCP/0037/modelica-uris.md index 5bd9cac20..6d8ced0e2 100644 --- a/RationaleMCP/0037/modelica-uris.md +++ b/RationaleMCP/0037/modelica-uris.md @@ -9,9 +9,14 @@ 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 not defined except for in the deprecated form of a Modelica URI. A tool should be able to interpret Modelica URIs both without _authority_ and with an empty _authority_. When _authority_ is present, any `/` separator following the _authority_ is just the separator between the _authority_ and the class reference, and not part of the class reference. +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 @@ -33,13 +38,16 @@ Among the proposed forms of class references below, there are some that are only 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_) - * Example: _modelica:///._ (empty _relclass_ with _authority_ present) + * 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_) From cf611138c9149acee5318ebd1ce87dd595486367 Mon Sep 17 00:00:00 2001 From: Henrik Tidefelt Date: Tue, 15 Sep 2020 12:41:48 +0200 Subject: [PATCH 09/29] Fix typo 'Stanard' -> 'Standard' --- RationaleMCP/0037/ReadMe.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/RationaleMCP/0037/ReadMe.md b/RationaleMCP/0037/ReadMe.md index 1cc1392c0..8388ed9ad 100644 --- a/RationaleMCP/0037/ReadMe.md +++ b/RationaleMCP/0037/ReadMe.md @@ -22,7 +22,7 @@ This MCP consists of three parts: 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 Stanard 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. +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. From ec1aa1b8c12bf39d07ed2cad47f02110353085fe Mon Sep 17 00:00:00 2001 From: Henrik Tidefelt Date: Tue, 15 Sep 2020 23:37:54 +0200 Subject: [PATCH 10/29] Add separate rationale for inclusion of relative class references --- RationaleMCP/0037/modelica-uris.md | 3 +- .../0037/relative-class-references.md | 51 +++++++++++++++++++ 2 files changed, 53 insertions(+), 1 deletion(-) create mode 100644 RationaleMCP/0037/relative-class-references.md diff --git a/RationaleMCP/0037/modelica-uris.md b/RationaleMCP/0037/modelica-uris.md index 6d8ced0e2..205f9e59b 100644 --- a/RationaleMCP/0037/modelica-uris.md +++ b/RationaleMCP/0037/modelica-uris.md @@ -26,12 +26,13 @@ Before going into the alternative new designs, let us first mention the current - _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_ -### Modelica URI class tree context +### 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 diff --git a/RationaleMCP/0037/relative-class-references.md b/RationaleMCP/0037/relative-class-references.md new file mode 100644 index 000000000..201bf35c4 --- /dev/null +++ b/RationaleMCP/0037/relative-class-references.md @@ -0,0 +1,51 @@ +# Rationale for relative class references + +To introduce relative class references has turned out to be the most controversial part of this MCP, and therefore deserves some use cases where a fully qualified class reference is impractical. + +Please note that this MCP doesn't claim that any package (the MSL in particular) should embrace the use of relative class references. It only provides a mechanism that some library authors may find very attractive for the maintainability of Modelica URIs and the organization of external resources. + +## Moving, renaming or deletion of a class + +These are some examples focusing on moving, renaming, or deletion of a class. + +### Class documentation refering to figures and plots of the same model + +Having a fully qualified reference would introduce a completely unnecessary maintenance problem — when the class is renamed or moved, it brings both its documentation and figures along with it, but a fully qualified class reference would still refer to the old place. With intelligent tool support, the class documentation can be automatically updated, but this is an artificial need coming from the use of fully qualified class references. + +### Images belonging to the documentation of a particular class + +For example, take the image +- _modelica://Modelica/Resources/Images/Blocks/Examples/PID_controller.png_ + +used the documentation of `Modelica.Blocks.Examples.PID_Controller`. With this organization, moving or renaming the class has no natural connection with moving or renaming the image in the same way, meaning that the file hierarchy under _Modelica/Resources_ can easily end up outdated compared to the class tree structure. + +If this image was instead referenced using the relative reference (see [modelica-uris.md]) +- _modelica:?resource=Images/typical-situation.png_ + +it would be stored as _Modelica/Blocks/Examples/PID_Controller/resources.d/Images/typical-situation.png_. Since the _resources.d_ directory belongs to `Modelica.Blocks.Examples.PID_Controller`, moving or renaming the class must bring along the _resources.d_ to the new location; otherwise there would be no way of referencing the resources within. This way, the problem of keeping the structure under _Modelica/Resources_ up-to-date with the class tree structure is solved in a very simple way. + +Tools don't need to be intelligent to make this work, they just need to do the bare minimum of moving the _resources.d_ along when a class is moved or renamed. (As a bonus, the documentation in _Modelica/package.mo_ wouldn't end up with an outdated example reference to this file.) + +### Data files belonging to a particular class + +For example, a source block whose only purpose is to deliver the data of a particular table file. The purpose of the block is to provide a Modelica interface to the table data, so no other model is supposed to reference the resource. Storing the table data inside the _resources.d_ of the block defining its Modelica interface will reduce the risk of bypassing the dedicated source block, avoid having the file laying around at some location far away from the model using it, cause no problems when the model is moved or renamed, and not leave any dangling data files is the model is deleted (as the _resources.d_ should normally be removed along with the class to which it belongs). + +### Experiment reference results + +Imagine the possibility to have several experiments defined for the same model, where each experiment can point to an external resource with a low resolution simulation result, which can both serve as reference result and be used to show figures without first performing simulation (allowing figures to be shown as part of the model documentation instead of just being linked). Again, such a result file is very tightly coupled to the class containing the experiment for which it serves as reference result. + +Storing such results in a directory structure under _Modelica/Resources_ implies a maintenance burden, as the one-to-one relation between an experiment and its reference result leaves no excuse for not matching directory hierarchy to the class tree. Storing such results file in the _resources.d_ of the class containing the experiment solves the maintenance problem. + +## Class duplication + +In addition to moving, renaming, and deletion of a class, one also have class duplication in mind. With globally organized external resources under _Modelica/Resources_, there is no immediate need to do anything with the external resources when a class is duplicated; the new class will refer to the resources of the original class. However, things are already starting to look strange when considering that a duplicated class (possibly a package) wouldn't be reflected under _Modelica/Resources_. Things are then getting worse if the original class is deleted, as the resource will still be stored as if the old class still existed. This just shows that class duplication isn't without issues in the current state of affairs. + +If a tool simply makes a copy of the _resources.d_ when a class is duplicated, relative class references can offer a solution if used wisely. When a resource is tied tightly to the class referencing it, it may not be so bad after all that one gets two different copes of the resource when the class is duplicated. When a resource isn't tied so tightly to the class referencing it, it should be stored with a class higher up in the class tree, where the level is found by considering questions such as: +- Along with which package should the resource be deleted? +- What is the deepest common parent package of all classes where the resource is expected to be used? + +## Tool implementation concerns + +As neither class moving, renaming, deletion, or duplication is covered by the Modelica specification, tools are free to come up with different strategies here. The simple approach of just moving, duplicating, or deleting _resources.d_ won't solve all problems, but as indicated above, this would be a good starting point, and can be improved by asking for user input regarding deletion and duplication. + +A more ambitious tool might also automatically update relative class references that would otherwise become dangling. Updating those that didn't become dangling would probably be bad, as these URIs were probably designed to remain unchanged when renaming, moving, or duplicating. However, a library developer that makes clever use of relative class references is less likely to end up with dangling references, and may not even want this sort of intelligence in the tool, preferring to become aware of the dangling references so that the underlying resource organization issues can be addressed. In other words, a tool doesn't necessarily have to be considered bad just because it only takes care of the _resources.d_ part and leaves the rest to the user. From 098295c99b640bdb90c782a8eafb74fa0bb2bbb1 Mon Sep 17 00:00:00 2001 From: Henrik Tidefelt Date: Wed, 16 Sep 2020 23:39:06 +0200 Subject: [PATCH 11/29] Add rationale for using '/' as separator in class references --- .../0037/class-reference-separator.md | 52 +++++++++++++++++++ RationaleMCP/0037/modelica-uris.md | 13 +++-- 2 files changed, 58 insertions(+), 7 deletions(-) create mode 100644 RationaleMCP/0037/class-reference-separator.md diff --git a/RationaleMCP/0037/class-reference-separator.md b/RationaleMCP/0037/class-reference-separator.md new file mode 100644 index 000000000..ca7e81e68 --- /dev/null +++ b/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 deprecated 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 deprecated 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/foo.png_ (deprecated form where _media_ would be the class reference) + * Wrong: _modelica:/media/foo.png_ (fully qualified form — not the intention) + * Correct: _modelica:.//media/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. diff --git a/RationaleMCP/0037/modelica-uris.md b/RationaleMCP/0037/modelica-uris.md index 205f9e59b..ae8adcf26 100644 --- a/RationaleMCP/0037/modelica-uris.md +++ b/RationaleMCP/0037/modelica-uris.md @@ -70,18 +70,17 @@ This leads to the alternative approach of making class references only through t ### 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 `/`. The advantage of doing this is that the URI path can then also be used to specify a relative file path to an external resource of the class, just like in the old Modelica URI format: -* _modelica:/Modelica.Electrical.Analog/media/foo.png_ +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_) -One has to watch out for the pitfal of just leaving the _relclass_ empty when there are additional path segments: - * Wrong: _modelica://media/foo.png_ (deprecated form where _media_ would be the class reference) - * Wrong: _modelica:/media/foo.png_ (fully qualified form — not the intention) - * Correct: _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. From 75307031aba0dcf3c612cbafb14f007a987dc06f Mon Sep 17 00:00:00 2001 From: Henrik Tidefelt Date: Fri, 25 Sep 2020 11:10:34 +0200 Subject: [PATCH 12/29] Fix typo in markdown link to other file Thanks, Malte. --- RationaleMCP/0037/modelica-uris.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/RationaleMCP/0037/modelica-uris.md b/RationaleMCP/0037/modelica-uris.md index ae8adcf26..441625b0c 100644 --- a/RationaleMCP/0037/modelica-uris.md +++ b/RationaleMCP/0037/modelica-uris.md @@ -94,7 +94,7 @@ This section is divided into one subsection for each type of resource being refe 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, [resoruce-directory.md]. +For further details see, [resource-directory.md]. ### Class view From 716988309638e46565f0ceb8e6ad2348188af688 Mon Sep 17 00:00:00 2001 From: Henrik Tidefelt Date: Fri, 25 Sep 2020 11:54:54 +0200 Subject: [PATCH 13/29] Fix typo Thanks, Malte. --- RationaleMCP/0037/resource-directory.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/RationaleMCP/0037/resource-directory.md b/RationaleMCP/0037/resource-directory.md index 0e4e7a773..bf57ee717 100644 --- a/RationaleMCP/0037/resource-directory.md +++ b/RationaleMCP/0037/resource-directory.md @@ -14,4 +14,4 @@ Note that the period (".") in the name _resources.d_ makes it distinguishable fr In the example Modelica URI above, assume `Modelica` is stored in _/Users/jdoe/modelica-packages/Modelica-4.3.2/Modelica_. Then, the resolved external resource is: - _/Users/jdoe/modelica-packages/Modelica-4.3.2/Modelica/Electrical/Analog/resources.d/media/foo.png_ -Note that the mapping of the fully qualified class name to a directory is the same regardless of whether the package itself uses a directory hierarchy for storage — the directory hierarchy for external resoruces is fixed, and it is only one of several options for the package itself to be stored in the same hierarchy. +Note that the mapping of the fully qualified class name to a directory is the same regardless of whether the package itself uses a directory hierarchy for storage — the directory hierarchy for external resources is fixed, and it is only one of several options for the package itself to be stored in the same hierarchy. From 3e20c0aa8f554d46b2e3f0c30ae039a90be025ce Mon Sep 17 00:00:00 2001 From: Henrik Tidefelt Date: Fri, 25 Sep 2020 13:38:53 +0200 Subject: [PATCH 14/29] Add section on what to do with the special 'Include' and 'Library' directories --- RationaleMCP/0037/resource-directory.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/RationaleMCP/0037/resource-directory.md b/RationaleMCP/0037/resource-directory.md index bf57ee717..3d177aa01 100644 --- a/RationaleMCP/0037/resource-directory.md +++ b/RationaleMCP/0037/resource-directory.md @@ -15,3 +15,19 @@ In the example Modelica URI above, assume `Modelica` is stored in _/Users/jdoe/m - _/Users/jdoe/modelica-packages/Modelica-4.3.2/Modelica/Electrical/Analog/resources.d/media/foo.png_ Note that the mapping of the fully qualified class name to a directory is the same regardless of whether the package itself uses a directory hierarchy for storage — the directory hierarchy for external resources is fixed, and it is only one of several options for the package itself to be stored in the same hierarchy. + +## Special resource directories + +The specification is currently giving special meaning to two external resource directores, specified using the deprecated form of Modelica URIs: +- _modelica://ModelicaLibraryName/Resources/Include_ +- _modelica://ModelicaLibraryName/Resources/Library_ + +As these get deprecated with this MCP, the following replacements are suggested: +- _modelica:~?resource=Include_ +- _modelica:~?resource=Library_ + +To use _Include_ and _Library_ directories associated with the top level package instead of the encapsulation barrier, there are at least two natural possibilities: +- Introduce something like a double tilde for reference to the current top level package: + - _modelica:~~?resource=Include +- Revert to the old strategy of a symbolically package-dependent URI: + - _modelica:/ModelicaLibraryName?resource=Include From 5bafae15c558f1c0be140ccd68297d26028d6839 Mon Sep 17 00:00:00 2001 From: Henrik Tidefelt Date: Mon, 19 Oct 2020 22:29:25 +0200 Subject: [PATCH 15/29] Describe use of fragment specifier in the context of a figure --- RationaleMCP/0037/modelica-uris.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/RationaleMCP/0037/modelica-uris.md b/RationaleMCP/0037/modelica-uris.md index 441625b0c..8666f4794 100644 --- a/RationaleMCP/0037/modelica-uris.md +++ b/RationaleMCP/0037/modelica-uris.md @@ -103,18 +103,24 @@ Different views of a class can be specified by using the `view` query: - _modelica:classref?view=icon_ — Class icon. * Example: `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). +- _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. +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_ -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). +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&plot=sumc1c2_ (appearing in the `Documentation.info` of the current class) + * Example: _modelica:?figure=voltcurr#sumc1c2_ (appearing in the `Documentation.info` of the current class) From fe4aa2b361a9b1b5340f6666fa87feb96edadc83 Mon Sep 17 00:00:00 2001 From: Henrik Tidefelt Date: Wed, 21 Oct 2020 22:56:25 +0200 Subject: [PATCH 16/29] Fix typo --- RationaleMCP/0037/modelica-uris.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/RationaleMCP/0037/modelica-uris.md b/RationaleMCP/0037/modelica-uris.md index 8666f4794..bdf8211d8 100644 --- a/RationaleMCP/0037/modelica-uris.md +++ b/RationaleMCP/0037/modelica-uris.md @@ -64,7 +64,7 @@ While powerful and tightly coupled with the rest of the Modelica language, the l 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_ — 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_ From 06f8c7b80aa5550767123c1322d933fe71228a8f Mon Sep 17 00:00:00 2001 From: Henrik Tidefelt Date: Wed, 21 Oct 2020 22:56:51 +0200 Subject: [PATCH 17/29] Mention possibility to redefine single tilde to mean top level package --- RationaleMCP/0037/resource-directory.md | 1 + 1 file changed, 1 insertion(+) diff --git a/RationaleMCP/0037/resource-directory.md b/RationaleMCP/0037/resource-directory.md index 3d177aa01..bc441ecf0 100644 --- a/RationaleMCP/0037/resource-directory.md +++ b/RationaleMCP/0037/resource-directory.md @@ -29,5 +29,6 @@ As these get deprecated with this MCP, the following replacements are suggested: To use _Include_ and _Library_ directories associated with the top level package instead of the encapsulation barrier, there are at least two natural possibilities: - Introduce something like a double tilde for reference to the current top level package: - _modelica:~~?resource=Include +- Redefine the single tilde to reference the top level package rather than the encapsulation barrier. - Revert to the old strategy of a symbolically package-dependent URI: - _modelica:/ModelicaLibraryName?resource=Include From f808f1d6615bea4197c2d243ad3d6882e21d6744 Mon Sep 17 00:00:00 2001 From: Henrik Tidefelt Date: Tue, 1 Dec 2020 09:08:37 +0100 Subject: [PATCH 18/29] Fix link markup --- RationaleMCP/0037/resource-directory.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/RationaleMCP/0037/resource-directory.md b/RationaleMCP/0037/resource-directory.md index bc441ecf0..992834932 100644 --- a/RationaleMCP/0037/resource-directory.md +++ b/RationaleMCP/0037/resource-directory.md @@ -3,7 +3,7 @@ Consider the following reference to an external resource: - _modelica:/Modelica/Electrical/Analog?resource=media/foo.png_ -The URI path part is the class reference, and could take different forms, as described in [modelica-uris.md]. The referenced class is denoted _current class_, here `Modelica.Electrical.Analog`. +The URI path part is the class reference, and could take different forms, as described in modelica-uris.md. The referenced class is denoted _current class_, here `Modelica.Electrical.Analog`. Here, the _media/foo.png_ is a relative file system path that is resolved within a resource directory associated with the current class. The details of this mapping for the deprecated _host_ form of a Modelica URI are omitted here; the following only applies to the non-deprecated forms, when the current Modelica package is stored in a file system hierarchy: - The fully qualified class name of the current class (after resolving any _relclass_ with respect to the class tree context) is mapped to a nested directory structure, with the constant directory name _resources.d_ (alternatively _package-resources_) appended. From 3b5cde8d2bf9f4c1dc88d8d13d31db827aeb62cb Mon Sep 17 00:00:00 2001 From: Henrik Tidefelt Date: Tue, 1 Dec 2020 09:10:31 +0100 Subject: [PATCH 19/29] Try to fix link markup again --- RationaleMCP/0037/resource-directory.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/RationaleMCP/0037/resource-directory.md b/RationaleMCP/0037/resource-directory.md index 992834932..947c4b862 100644 --- a/RationaleMCP/0037/resource-directory.md +++ b/RationaleMCP/0037/resource-directory.md @@ -3,7 +3,7 @@ Consider the following reference to an external resource: - _modelica:/Modelica/Electrical/Analog?resource=media/foo.png_ -The URI path part is the class reference, and could take different forms, as described in modelica-uris.md. The referenced class is denoted _current class_, here `Modelica.Electrical.Analog`. +The URI path part is the class reference, and could take different forms, as described in [modelica-uris.md](modelica-uris.md). The referenced class is denoted _current class_, here `Modelica.Electrical.Analog`. Here, the _media/foo.png_ is a relative file system path that is resolved within a resource directory associated with the current class. The details of this mapping for the deprecated _host_ form of a Modelica URI are omitted here; the following only applies to the non-deprecated forms, when the current Modelica package is stored in a file system hierarchy: - The fully qualified class name of the current class (after resolving any _relclass_ with respect to the class tree context) is mapped to a nested directory structure, with the constant directory name _resources.d_ (alternatively _package-resources_) appended. From af28f847721a5bef03d8aaab6c07bf39dc9e6c3c Mon Sep 17 00:00:00 2001 From: Henrik Tidefelt Date: Tue, 1 Dec 2020 09:23:08 +0100 Subject: [PATCH 20/29] Clarify resources.d location for classes not stored in a directory --- RationaleMCP/0037/resource-directory.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/RationaleMCP/0037/resource-directory.md b/RationaleMCP/0037/resource-directory.md index 947c4b862..90f77dd95 100644 --- a/RationaleMCP/0037/resource-directory.md +++ b/RationaleMCP/0037/resource-directory.md @@ -14,7 +14,8 @@ Note that the period (".") in the name _resources.d_ makes it distinguishable fr In the example Modelica URI above, assume `Modelica` is stored in _/Users/jdoe/modelica-packages/Modelica-4.3.2/Modelica_. Then, the resolved external resource is: - _/Users/jdoe/modelica-packages/Modelica-4.3.2/Modelica/Electrical/Analog/resources.d/media/foo.png_ -Note that the mapping of the fully qualified class name to a directory is the same regardless of whether the package itself uses a directory hierarchy for storage — the directory hierarchy for external resources is fixed, and it is only one of several options for the package itself to be stored in the same hierarchy. +Note that the mapping of the fully qualified class name to a directory is the same regardless of whether the package itself uses a directory hierarchy for storage — the directory hierarchy for external resources is fixed, and it is only one of several options for the package itself to be stored in the same hierarchy. In particular, it does not matter whether the top level file is _package.mo_ or a file named according to the class it contains. For example, consider the top level function `Foo` stored in _/Users/jdoe/modelica-packages/Foo.mo_. Then this is the location of the resource _modelica:/Foo?resource=media/foo.png_: +- _/Users/jdoe/modelica-packages/Foo/resources.d/media/foo.png_ ## Special resource directories From 8baeb7a02c95e8a160a195ffd6021467391543ad Mon Sep 17 00:00:00 2001 From: Henrik Tidefelt Date: Wed, 15 Mar 2023 21:44:15 +0100 Subject: [PATCH 21/29] Remove obsolete MCP link for figures and plots --- RationaleMCP/0037/ReadMe.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/RationaleMCP/0037/ReadMe.md b/RationaleMCP/0037/ReadMe.md index 8388ed9ad..939f56589 100644 --- a/RationaleMCP/0037/ReadMe.md +++ b/RationaleMCP/0037/ReadMe.md @@ -27,7 +27,7 @@ Having `resolveURI` in the Modelica Language Specification instead of `loadResou 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 ([MCP-0033](https://github.com/modelica/ModelicaSpecification/pull/2482)). + - Figures and plots. - Figure style sheets (topic for future MCP). - Named experiments (topic for future MCP). - A component of the instantiated class. From 34e6bef6afb48fa518990e7579bf6ad05720ec1f Mon Sep 17 00:00:00 2001 From: Henrik Tidefelt Date: Wed, 15 Mar 2023 21:44:28 +0100 Subject: [PATCH 22/29] Fix typo --- RationaleMCP/0037/ReadMe.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/RationaleMCP/0037/ReadMe.md b/RationaleMCP/0037/ReadMe.md index 939f56589..1c317eb97 100644 --- a/RationaleMCP/0037/ReadMe.md +++ b/RationaleMCP/0037/ReadMe.md @@ -32,7 +32,7 @@ Besides addressing the problem with case insensitivity of the _host_ part of a U - 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 amiguity 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. +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. From a900b945dcb7ad8b6350c9d2689ae39b02b65bdf Mon Sep 17 00:00:00 2001 From: Henrik Tidefelt Date: Fri, 17 Mar 2023 16:27:05 +0100 Subject: [PATCH 23/29] Don't deprecate current Modelica URIs --- RationaleMCP/0037/ReadMe.md | 2 +- RationaleMCP/0037/class-reference-separator.md | 10 +++++----- RationaleMCP/0037/modelica-uris.md | 7 +++++-- RationaleMCP/0037/resolve-uri.md | 2 +- RationaleMCP/0037/resource-directory.md | 6 +++--- 5 files changed, 15 insertions(+), 12 deletions(-) diff --git a/RationaleMCP/0037/ReadMe.md b/RationaleMCP/0037/ReadMe.md index 1c317eb97..3039d2cd6 100644 --- a/RationaleMCP/0037/ReadMe.md +++ b/RationaleMCP/0037/ReadMe.md @@ -37,7 +37,7 @@ The file system storage of external resources together with a Modelica class mak ## 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. However, the existing Modelica URIs will become a deprecated form according to this MCP. +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. diff --git a/RationaleMCP/0037/class-reference-separator.md b/RationaleMCP/0037/class-reference-separator.md index ca7e81e68..7adab0725 100644 --- a/RationaleMCP/0037/class-reference-separator.md +++ b/RationaleMCP/0037/class-reference-separator.md @@ -1,6 +1,6 @@ # 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 deprecated form of Modelica URIs use `.`. This document gives reasons for and against the current proposal. +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) @@ -13,7 +13,7 @@ Most class names using normal Modelica syntax can be directly copied and pasted ### 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 deprecated Modelica URI format: +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.) @@ -41,9 +41,9 @@ With `.` as separator, on the other hand, one obtains: ### 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/foo.png_ (deprecated form where _media_ would be the class reference) - * Wrong: _modelica:/media/foo.png_ (fully qualified form — not the intention) - * Correct: _modelica:.//media/foo.png_ (empty _relclass_; just a `.` cannot be mistaken for ) + * 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 diff --git a/RationaleMCP/0037/modelica-uris.md b/RationaleMCP/0037/modelica-uris.md index bdf8211d8..74fe9e35b 100644 --- a/RationaleMCP/0037/modelica-uris.md +++ b/RationaleMCP/0037/modelica-uris.md @@ -11,9 +11,12 @@ Users that are unsure about the details of the general URI syntax are recommende ## 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 `.`. -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. +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_ @@ -23,7 +26,7 @@ As usual, some characters need to be URL encoded when put in a URI. For instanc 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). +- _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 diff --git a/RationaleMCP/0037/resolve-uri.md b/RationaleMCP/0037/resolve-uri.md index db10586ec..b1d8a7441 100644 --- a/RationaleMCP/0037/resolve-uri.md +++ b/RationaleMCP/0037/resolve-uri.md @@ -6,7 +6,7 @@ The result of `resolveURI(uri)` is a `String` giving the absolute filename of th `resolveURI` accepts two kinds of URIs: - _file:///…_ — only allowing absolute _file_ URIs -- _modelica:…_ — any Modelica URI except the deprecated _host_ form +- _modelica:…?…_ — any Modelica URI with a query part (which excludes the legacy _host_ form) The reason that relative file URIs are not supported by `resolveURI` is that the base URI would most naturally be the file in which the Modelica source code of the `resolveURI` expression is stored, but a Modelica tool is not required to store classes in a file system, so this also encourages the use of Modelica URIs to handle resources attached to a Modelica class. diff --git a/RationaleMCP/0037/resource-directory.md b/RationaleMCP/0037/resource-directory.md index 90f77dd95..b5d6dedca 100644 --- a/RationaleMCP/0037/resource-directory.md +++ b/RationaleMCP/0037/resource-directory.md @@ -5,7 +5,7 @@ Consider the following reference to an external resource: The URI path part is the class reference, and could take different forms, as described in [modelica-uris.md](modelica-uris.md). The referenced class is denoted _current class_, here `Modelica.Electrical.Analog`. -Here, the _media/foo.png_ is a relative file system path that is resolved within a resource directory associated with the current class. The details of this mapping for the deprecated _host_ form of a Modelica URI are omitted here; the following only applies to the non-deprecated forms, when the current Modelica package is stored in a file system hierarchy: +Here, the _media/foo.png_ is a relative file system path that is resolved within a resource directory associated with the current class. The details of this mapping for the legacy form of a Modelica URI are omitted here; the following only applies to the non-legacy forms, when the current Modelica package is stored in a file system hierarchy: - The fully qualified class name of the current class (after resolving any _relclass_ with respect to the class tree context) is mapped to a nested directory structure, with the constant directory name _resources.d_ (alternatively _package-resources_) appended. - The relative file system path is relative to _resources.d_ and may not contain the special path segments "." or "..". @@ -19,11 +19,11 @@ Note that the mapping of the fully qualified class name to a directory is the sa ## Special resource directories -The specification is currently giving special meaning to two external resource directores, specified using the deprecated form of Modelica URIs: +The specification is currently giving special meaning to two external resource directores, specified using the legacy form of Modelica URIs: - _modelica://ModelicaLibraryName/Resources/Include_ - _modelica://ModelicaLibraryName/Resources/Library_ -As these get deprecated with this MCP, the following replacements are suggested: +As these are considered a legacy form as of this MCP, the following replacements are suggested: - _modelica:~?resource=Include_ - _modelica:~?resource=Library_ From 14e8d984b6eb5565ff4f6d22157274dfeb68ec50 Mon Sep 17 00:00:00 2001 From: Henrik Tidefelt Date: Thu, 23 Mar 2023 17:52:43 +0100 Subject: [PATCH 24/29] Add another line to the revision history --- RationaleMCP/0037/ReadMe.md | 1 + 1 file changed, 1 insertion(+) diff --git a/RationaleMCP/0037/ReadMe.md b/RationaleMCP/0037/ReadMe.md index 3039d2cd6..2635579ac 100644 --- a/RationaleMCP/0037/ReadMe.md +++ b/RationaleMCP/0037/ReadMe.md @@ -10,6 +10,7 @@ This MCP defines the next generation handling of external resources in Modelica. | 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". From 30c14f162e2388e6bb4bd35138046ac6e8f49ed4 Mon Sep 17 00:00:00 2001 From: Henrik Tidefelt Date: Tue, 24 Oct 2023 08:37:00 +0200 Subject: [PATCH 25/29] Clarify that resolveURI is for the 'resource' query --- RationaleMCP/0037/resolve-uri.md | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/RationaleMCP/0037/resolve-uri.md b/RationaleMCP/0037/resolve-uri.md index b1d8a7441..bd4e81df5 100644 --- a/RationaleMCP/0037/resolve-uri.md +++ b/RationaleMCP/0037/resolve-uri.md @@ -1,16 +1,21 @@ # The resolveURI operator -An operator with function syntax called `resolveURI` is introduced. Compared to `loadResource`, it is more powerful, will have more clearly defined semantics, and is properly defined as Modelica lanugage feature instead of bypassing the Modelica Language Specification by means of `ModelicaServices`. +An operator with function syntax called `resolveURI` is introduced. +Compared to `loadResource`, it is more powerful, will have more clearly defined semantics, and is properly defined as Modelica lanugage feature instead of bypassing the Modelica Language Specification by means of `ModelicaServices`. -The result of `resolveURI(uri)` is a `String` giving the absolute filename of the external resource referenced by `uri`. Unlike a normal function, it knows about its call site, so that it can apply normal lookup rules. +The result of `resolveURI(uri)` is a `String` giving the absolute filename of the external resource referenced by `uri`. +Unlike a normal function, it knows about its call site, so that it can apply normal lookup rules. `resolveURI` accepts two kinds of URIs: - _file:///…_ — only allowing absolute _file_ URIs -- _modelica:…?…_ — any Modelica URI with a query part (which excludes the legacy _host_ form) +- _modelica:…?resource=…_ — a Modelica URI with a `resource` query (which excludes the legacy _host_ form) The reason that relative file URIs are not supported by `resolveURI` is that the base URI would most naturally be the file in which the Modelica source code of the `resolveURI` expression is stored, but a Modelica tool is not required to store classes in a file system, so this also encourages the use of Modelica URIs to handle resources attached to a Modelica class. -For a Modelica URI, `resolveURI` provides a context for lookup-based Modelica URIs, namely the class containing the `resolveURI` expression. The following example illustrates how `resolveURI` gives context to a lookup-based URI: +While the initial design restricts the use Modelica URIs to those with a `resource` query, future extension to other queries will be possible whenever a query can be meaningfully resolved to a `String` result. + +For a Modelica URI, `resolveURI` provides a context for lookup-based Modelica URIs, namely the class containing the `resolveURI` expression. +The following example illustrates how `resolveURI` gives context to a lookup-based URI: ``` package P model M @@ -26,7 +31,8 @@ package P M m(uri = "modelica:A?resource=table.mat"); end P; ``` -Here, the lookup of `uri` doesn't take place where the string literal appears (namely `P`, which would have resulted in _…/P/A/resources.d/table.mat_). Instead, the lookup happens in the context `P.M`, resulting in `m.filename` being _…/P/M/A/resources.d/table.mat_. +Here, the lookup of `uri` doesn't take place where the string literal appears (namely `P`, which would have resulted in _…/P/A/resources.d/table.mat_). +Instead, the lookup happens in the context `P.M`, resulting in `m.filename` being _…/P/M/A/resources.d/table.mat_. The example above may seem counter-intuitive, but the example is contrived and the potential confusion is typically avoided by applying `resolveURI` directly to a string literal; then the context of the string literal coincides with the context given by the `resolveURI` expression. @@ -35,7 +41,8 @@ Note that a `resolveURI` expression is an expression resulting in an absolute fi ## Evaluation semantics It would make sense to standardize on either of the following two variants: -- It only operates on constant strings. This way, application of lookup rules doesn't require a runtime representation of the class tree. +- It only operates on constant strings. + This way, application of lookup rules doesn't require a runtime representation of the class tree. - It only evaluates at runtime, allowing a built simulation to be transferred from one tool installation to another. A clear drawback of runtime evaluation is that it becomes impossible to make external resources part of a `constant` expression — the variability of a `resolveURI` expression would be no less than `parameter`. From 5045cb0e06f5aa547844c3577c405969da9c7327 Mon Sep 17 00:00:00 2001 From: Henrik Tidefelt Date: Wed, 9 Apr 2025 17:34:09 +0200 Subject: [PATCH 26/29] Fix typo in explanation of modelica:./relclass --- RationaleMCP/0037/modelica-uris.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/RationaleMCP/0037/modelica-uris.md b/RationaleMCP/0037/modelica-uris.md index 74fe9e35b..c6f991cc5 100644 --- a/RationaleMCP/0037/modelica-uris.md +++ b/RationaleMCP/0037/modelica-uris.md @@ -47,7 +47,7 @@ These are the different ways of referencing a class, where the _host_, _fullclas * 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. +- _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_ `/.`) From dcdcc8cc34976443de537b89213d58cb64783399 Mon Sep 17 00:00:00 2001 From: Henrik Tidefelt Date: Mon, 20 Apr 2026 08:01:51 +0200 Subject: [PATCH 27/29] Update list of resource directories with special meaning --- RationaleMCP/0037/resource-directory.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/RationaleMCP/0037/resource-directory.md b/RationaleMCP/0037/resource-directory.md index b5d6dedca..7684da27d 100644 --- a/RationaleMCP/0037/resource-directory.md +++ b/RationaleMCP/0037/resource-directory.md @@ -19,13 +19,17 @@ Note that the mapping of the fully qualified class name to a directory is the sa ## Special resource directories -The specification is currently giving special meaning to two external resource directores, specified using the legacy form of Modelica URIs: -- _modelica://ModelicaLibraryName/Resources/Include_ -- _modelica://ModelicaLibraryName/Resources/Library_ +The specification is currently giving special meaning to a few external resource directores, specified using the legacy form of Modelica URIs: +- _modelica:/TopPackage/Resources/Include_ +- _modelica:/TopPackage/Resources/Library_ +- _modelica:/TopPackage/Resources/Source_ +- _modelica:/TopPackage/Resources/Language_ As these are considered a legacy form as of this MCP, the following replacements are suggested: - _modelica:~?resource=Include_ - _modelica:~?resource=Library_ +- _modelica:~?resource=Source_ +- _modelica:~?resource=Language_ To use _Include_ and _Library_ directories associated with the top level package instead of the encapsulation barrier, there are at least two natural possibilities: - Introduce something like a double tilde for reference to the current top level package: From b6902be602e86f4899e59bada74fe37784c8e934 Mon Sep 17 00:00:00 2001 From: Henrik Tidefelt Date: Mon, 20 Apr 2026 09:03:25 +0200 Subject: [PATCH 28/29] Define vendor-specific resource directories, analogous to annotations --- RationaleMCP/0037/resource-directory.md | 28 ++++++++++++++++++------- 1 file changed, 20 insertions(+), 8 deletions(-) diff --git a/RationaleMCP/0037/resource-directory.md b/RationaleMCP/0037/resource-directory.md index 7684da27d..a382c36b7 100644 --- a/RationaleMCP/0037/resource-directory.md +++ b/RationaleMCP/0037/resource-directory.md @@ -14,9 +14,19 @@ Note that the period (".") in the name _resources.d_ makes it distinguishable fr In the example Modelica URI above, assume `Modelica` is stored in _/Users/jdoe/modelica-packages/Modelica-4.3.2/Modelica_. Then, the resolved external resource is: - _/Users/jdoe/modelica-packages/Modelica-4.3.2/Modelica/Electrical/Analog/resources.d/media/foo.png_ -Note that the mapping of the fully qualified class name to a directory is the same regardless of whether the package itself uses a directory hierarchy for storage — the directory hierarchy for external resources is fixed, and it is only one of several options for the package itself to be stored in the same hierarchy. In particular, it does not matter whether the top level file is _package.mo_ or a file named according to the class it contains. For example, consider the top level function `Foo` stored in _/Users/jdoe/modelica-packages/Foo.mo_. Then this is the location of the resource _modelica:/Foo?resource=media/foo.png_: +Note that the mapping of the fully qualified class name to a directory is the same regardless of whether the package itself uses a directory hierarchy for storage — the directory hierarchy for external resources is fixed, and it is only one of several options for the package itself to be stored in the same hierarchy. In particular, it does not matter whether the top level file is _package.mo_ or a file named according to the class it contains. For example, consider the top level function `Foo` stored in _/Users/jdoe/modelica-packages/Foo.mo_. Then this is the location of the resource _modelica:/Foo?resource=media/foo.png_: - _/Users/jdoe/modelica-packages/Foo/resources.d/media/foo.png_ +## Vendor-specific directories + +Analogous to vendor-specific annotations, the directory _resources.d/\_\_NameOfVendor_ is reserved for vendor-specific use. +The _NameOfVendor_ consists of only digits and letters, and shall only convey the name of the vendor defining the meaning of the directory content. + +The Modelica Association uses the vendor name _MA_. +Coordination between the different projects under the Modelica Association enables resources for both, say, the Modelica specification and the Modelica Standard Library, to coexist in this directory. + +In addition to preventing conflicts between different vendors, and between vendors and library authors, the idea of vendor-specific directories might also turn out to be useful if the Modelica language would have to support "layered standards" in the future. + ## Special resource directories The specification is currently giving special meaning to a few external resource directores, specified using the legacy form of Modelica URIs: @@ -26,14 +36,16 @@ The specification is currently giving special meaning to a few external resource - _modelica:/TopPackage/Resources/Language_ As these are considered a legacy form as of this MCP, the following replacements are suggested: -- _modelica:~?resource=Include_ -- _modelica:~?resource=Library_ -- _modelica:~?resource=Source_ -- _modelica:~?resource=Language_ +- _modelica:~?resource=\_\_MA/Include_ +- _modelica:~?resource=\_\_MA/Library_ +- _modelica:~?resource=\_\_MA/Source_ +- _modelica:~?resource=\_\_MA/Language_ + +By placing the directories under _\_\_MA_, there is no risk of conflict if the Modelica specification would introduce more resource directories with special meaning in the future. -To use _Include_ and _Library_ directories associated with the top level package instead of the encapsulation barrier, there are at least two natural possibilities: +To use directories associated with the top level package instead of the encapsulation barrier, there are at least two natural possibilities: - Introduce something like a double tilde for reference to the current top level package: - - _modelica:~~?resource=Include + - _modelica:~~?resource=\_\_MA/Include - Redefine the single tilde to reference the top level package rather than the encapsulation barrier. - Revert to the old strategy of a symbolically package-dependent URI: - - _modelica:/ModelicaLibraryName?resource=Include + - _modelica:/ModelicaLibraryName?resource=\_\_MA/Include From 749a880dec1f5dbb6db36d41c49fb50c7e6071df Mon Sep 17 00:00:00 2001 From: Henrik Tidefelt Date: Wed, 22 Apr 2026 14:42:47 +0200 Subject: [PATCH 29/29] Expand on the relation to layered standards --- RationaleMCP/0037/resource-directory.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/RationaleMCP/0037/resource-directory.md b/RationaleMCP/0037/resource-directory.md index a382c36b7..67fab95b7 100644 --- a/RationaleMCP/0037/resource-directory.md +++ b/RationaleMCP/0037/resource-directory.md @@ -26,6 +26,8 @@ The Modelica Association uses the vendor name _MA_. Coordination between the different projects under the Modelica Association enables resources for both, say, the Modelica specification and the Modelica Standard Library, to coexist in this directory. In addition to preventing conflicts between different vendors, and between vendors and library authors, the idea of vendor-specific directories might also turn out to be useful if the Modelica language would have to support "layered standards" in the future. +With one directory associated with each layered standard, it might be possible to map many layered standards to Modelica without the need for vendor-specific annotations. +At lease, any information that would be a candidate for going into a vendor-specific class annotation could go into a file associated with the class instead. ## Special resource directories