From 31ab77690549de8de1a922e22c4affd8a00c7b36 Mon Sep 17 00:00:00 2001 From: Henrik Tidefelt Date: Tue, 29 Nov 2022 00:28:11 +0100 Subject: [PATCH 01/11] Initial content of source-locations.md --- RationaleMCP/0031/source-locations.md | 77 +++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) create mode 100644 RationaleMCP/0031/source-locations.md diff --git a/RationaleMCP/0031/source-locations.md b/RationaleMCP/0031/source-locations.md new file mode 100644 index 000000000..35296be75 --- /dev/null +++ b/RationaleMCP/0031/source-locations.md @@ -0,0 +1,77 @@ +# Source locations + +To fully serve as a format for intermediate representation of translation of full Modelica, the Flat Modelica code can be decorated with source location information pointing back to the original full Modelica model (or other source of the Flat Modelica code). + + +## Design goals + +Some design goals to keep in mind when comparing the design alternatives: +- The detailed format of a source location needs to be flexible to serve the needs of different tools. +- A tool should be able to ignore source locations originating from other tools. +- Source locations may be needed on many levels of the Flat Modelica code, including component declarations, equations, modifications, and expressions. +- Reduced Flat Modelica soruce code human readability is a concern when soruce locations are added. +- Simple compression of the source locations could be handy. + + +## Design alternatives + +Some design alternatives are given below, along with their advantages and disadvantages. + + +### External source location table + +The Flat Modelica code is accompanied by a separate table with source location details. +The table can be stored in an annotation or be provided as a separate file. + +When stored in an annotation, it has the form +``` +record SourceLocations + String format "String used to identify the formal of each table row"; + String table "One source location per line, with lines numbered from zero"; +end SourceLocations; +``` + +The `format` must not contain any newline, and all tool vendors must use a string starting with a vendor-annotation prefix. +For example: +``` +SourceLocations(format = "__Wolfram file:row:col", table = "...") +``` +(In the future, there could be standardized formats that all Flat Modelica tools are expected to recognize.) + +Note that it is possible to store source locations compactly in various ways, such as only specifying that differs from the row before: +``` +A/package.mo:1:0 +::4 +::10 +:2:0 +::7 +A/B/package.mo:5:7 +::9 +A/package.mo:3:5 +``` + +When provided as a separate file, the file shall have the following header right before the rows of table data: +``` +//! flat source +//! Format: FORMAT +``` + +In the Flat Modelica code, a source location is attached to an expression or constuct using the `@` operator: +``` +package 'MyModel' + model 'MyModel' + parameter Real 'p' = 42 @21; // Attach 21 to binding expression "42" + Real 'x'(min = 0 @22); // Attach 22 to modification "0" + Real 'y' = @23 'x'; // Attach 23 to component declaration + equation + der('x') = @24 1; // Attach 24 to equation + end 'MyModel'; +end 'MyModel'; +``` + +The precedence of `@` is lower than the expression operators, so that no parentheses are needed when attaching a source locaiton to a modification or binding. + + +## Conclusions + +None yet. From 9d49927fb712f3f0649f2367024fd9060fe871bc Mon Sep 17 00:00:00 2001 From: Henrik Tidefelt Date: Tue, 29 Nov 2022 00:33:50 +0100 Subject: [PATCH 02/11] Tick-off roadmap item corresponding to this PR --- RationaleMCP/0031/ReadMe.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/RationaleMCP/0031/ReadMe.md b/RationaleMCP/0031/ReadMe.md index 7e11cef18..5ddf0ccad 100644 --- a/RationaleMCP/0031/ReadMe.md +++ b/RationaleMCP/0031/ReadMe.md @@ -73,7 +73,7 @@ These are subtopics that are considered necessary to resolve for a first version - [x] Figure out what to do with synchronous features. [Design](https://github.com/modelica/ModelicaSpecification/blob/MCP/0031%2Bsynchronous/RationaleMCP/0031/differences.md#clock-partitions), [PR with discussion](https://github.com/modelica/ModelicaSpecification/pull/3240) - [x] Event handling semantics is preserved as in Modelica. - [ ] Get rid of `when initial()` and `when`-equations inside `if` and `for`. [Design](https://github.com/modelica/ModelicaSpecification/blob/MCP/0031%2Bsimplify-when/RationaleMCP/0031/differences.md#when-equations), [PR with discussion](https://github.com/modelica/ModelicaSpecification/pull/3258) -- [ ] Source locations pointing back to the original Modelica code. [Design](https://github.com/modelica/ModelicaSpecification/blob/MCP/0031%2Bsource-locations/RationaleMCP/0031/source-locations.md), [PR with discussion](https://github.com/modelica/ModelicaSpecification/pull/3295) +- [x] Source locations pointing back to the original Modelica code. [Design](https://github.com/modelica/ModelicaSpecification/blob/MCP/0031%2Bsource-locations/RationaleMCP/0031/source-locations.md), [PR with discussion](https://github.com/modelica/ModelicaSpecification/pull/3295) - [ ] Settle the name (currently _Flat Modelica_), considering that scalarization isn't mandatory. [Design](https://github.com/modelica/ModelicaSpecification/blob/MCP/0031%2Bname-of-the-game/RationaleMCP/0031/name-of-the-game.md), [PR with discussion](https://github.com/modelica/ModelicaSpecification/pull/3224) ### Flat Modelica 0.1+…1.0 (future MCPs) From bf554e14e87ff4d74766de508758747a962ac4e2 Mon Sep 17 00:00:00 2001 From: Henrik Tidefelt Date: Wed, 30 Nov 2022 08:29:51 +0100 Subject: [PATCH 03/11] Fix case in external source location table header --- RationaleMCP/0031/source-locations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/RationaleMCP/0031/source-locations.md b/RationaleMCP/0031/source-locations.md index 35296be75..d064e6062 100644 --- a/RationaleMCP/0031/source-locations.md +++ b/RationaleMCP/0031/source-locations.md @@ -53,7 +53,7 @@ A/package.mo:3:5 When provided as a separate file, the file shall have the following header right before the rows of table data: ``` //! flat source -//! Format: FORMAT +//! format: FORMAT ``` In the Flat Modelica code, a source location is attached to an expression or constuct using the `@` operator: From 3f79c39f91c9c534e119550a2117d28cd4e9c97c Mon Sep 17 00:00:00 2001 From: Henrik Tidefelt Date: Wed, 30 Nov 2022 10:40:33 +0100 Subject: [PATCH 04/11] Improvements based on today's web meeting discussions --- RationaleMCP/0031/source-locations.md | 130 +++++++++++++++++--------- 1 file changed, 88 insertions(+), 42 deletions(-) diff --git a/RationaleMCP/0031/source-locations.md b/RationaleMCP/0031/source-locations.md index d064e6062..0b08ecc57 100644 --- a/RationaleMCP/0031/source-locations.md +++ b/RationaleMCP/0031/source-locations.md @@ -2,6 +2,14 @@ To fully serve as a format for intermediate representation of translation of full Modelica, the Flat Modelica code can be decorated with source location information pointing back to the original full Modelica model (or other source of the Flat Modelica code). +Each _source location decoration_ (or simply _decoration_ in this context) attaches some kind of source location information to a specific construct in the Flat Modelica code. + +Design decisions include: +- Details of what a source location consists of: standardized or open for tool-specific choices? +- Syntax of information included directly in a decoration. +- Syntax for how a decoration is attached to a Flat Modelica construct. +- How to handle need for (optional) big tables of verbose source location data. + ## Design goals @@ -13,65 +21,103 @@ Some design goals to keep in mind when comparing the design alternatives: - Simple compression of the source locations could be handy. -## Design alternatives - -Some design alternatives are given below, along with their advantages and disadvantages. - - -### External source location table -The Flat Modelica code is accompanied by a separate table with source location details. -The table can be stored in an annotation or be provided as a separate file. +## Tool-specific table of source location details -When stored in an annotation, it has the form -``` -record SourceLocations - String format "String used to identify the formal of each table row"; - String table "One source location per line, with lines numbered from zero"; -end SourceLocations; -``` - -The `format` must not contain any newline, and all tool vendors must use a string starting with a vendor-annotation prefix. +The Flat Modelica package level annotation may have a `SourceLocations`-annotation. +There is no standardized content for this annotation, so it is currently only possible to use with vendor-specific annotations inside. For example: ``` -SourceLocations(format = "__Wolfram file:row:col", table = "...") +package 'MyModel' +model 'MyModel' +… +end 'MyModel'; +annotation(SourceLocations(__Wolfram(sourceLocationsFile = "MyModel.loc"))); +end 'MyModel'; ``` -(In the future, there could be standardized formats that all Flat Modelica tools are expected to recognize.) -Note that it is possible to store source locations compactly in various ways, such as only specifying that differs from the row before: +As an alternative to pointing to a vendor-specific external file, it is also possible to include information directly in the annotation: ``` -A/package.mo:1:0 -::4 -::10 -:2:0 -::7 -A/B/package.mo:5:7 -::9 -A/package.mo:3:5 +annotation(SourceLocations(__OpenModelica( + table = { + SourceLocation(file = "MoModel.mo", start = {1, 2}, end = {1, 7}), + SourceLocation(…), + … + })); ``` -When provided as a separate file, the file shall have the following header right before the rows of table data: -``` -//! flat source -//! format: FORMAT -``` +In the future, there could be standardized contents for the `SourceLocations` that all Flat Modelica tools are expected to recognize. + + +## Syntax of information present in a source location decoration + +### Design alternatives + +Alternatives include: +- Just an integer to be used with a tool-specific table of source location details. +- Predefined record to avoid need for tool-specific table. (Details to be designed). +- Use `annotation(SourceLocation(…))` to avoid need for attachment operator. + +The alternatives above could also be combined in different ways: +- Number of supported formats: + - Standardize on just one of the alternatives. + - Allow more than one of the alternatives. +- Number of informations included in a single source location decoration + - Just a single piece of information. + - Multiple pieces of information (possibly in different formats). -In the Flat Modelica code, a source location is attached to an expression or constuct using the `@` operator: +### Conclusion + +None yet, but all discussion so far has pointed in the direction of just a single integer. + + +## Syntax for source location decoration attachment + +Given a decision on what information that should be present in a decoration, the next question is which syntax to use for attaching it to a Flat Modelica construct. + +### Design alternatives + +#### Low precedence infix `@` operator + +Use infix `@` as decoration attachment operator: ``` package 'MyModel' - model 'MyModel' - parameter Real 'p' = 42 @21; // Attach 21 to binding expression "42" - Real 'x'(min = 0 @22); // Attach 22 to modification "0" - Real 'y' = @23 'x'; // Attach 23 to component declaration - equation - der('x') = @24 1; // Attach 24 to equation - end 'MyModel'; +model 'MyModel' + parameter Real 'p' = 42 @21; // Attach 21 to binding expression "42" + Real 'x'(min = 0 @22); // Attach 22 to modification "0" + Real 'y' = @23 'x'; // Attach 23 to component declaration +equation + der('x') = @24 1; // Attach 24 to equation + der('y') = 1 @25; // Attach 25 to "1" +end 'MyModel'; +annotation(SourceLocations(…)); end 'MyModel'; ``` The precedence of `@` is lower than the expression operators, so that no parentheses are needed when attaching a source locaiton to a modification or binding. +#### Low precedence infix `!` operator + +Similar to the `@` operator above, but using `!` instead. + +#### Allow use of annotations in new places + +Instead of using an operator, one could use annotations if allowing them in new places: +``` +package 'MyModel' +model 'MyModel' + parameter Real 'p' = (42 annotation(SourceLocation = 21)); // Attach 21 to binding expression "42" + Real 'x'(min = 0 annotation(SourceLocation = 22)); // Attach 22 to modification "0" + Real 'y' = 'x' annotation(SourceLocation = 23)); // Attach 23 to component declaration +equation + der('x') = 1 annotation(SourceLocation = 24); // Attach 24 to equation + der('y') = (1 annotation(SourceLocation = 25)); // Attach 25 to "1" +end 'MyModel'; +annotation(SourceLocations(…)); +end 'MyModel'; +``` + -## Conclusions +### Conclusions None yet. From 2dca71911309f630fdadd497a08dbeb806ae987c Mon Sep 17 00:00:00 2001 From: Henrik Tidefelt Date: Wed, 30 Nov 2022 12:39:05 +0100 Subject: [PATCH 05/11] Don't over-stress tool-specific nature of source location table --- RationaleMCP/0031/source-locations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/RationaleMCP/0031/source-locations.md b/RationaleMCP/0031/source-locations.md index 0b08ecc57..b34289a17 100644 --- a/RationaleMCP/0031/source-locations.md +++ b/RationaleMCP/0031/source-locations.md @@ -54,7 +54,7 @@ In the future, there could be standardized contents for the `SourceLocations` th ### Design alternatives Alternatives include: -- Just an integer to be used with a tool-specific table of source location details. +- Just an integer to be used with a separate table of details provided by `SourceLocations`-annotation. - Predefined record to avoid need for tool-specific table. (Details to be designed). - Use `annotation(SourceLocation(…))` to avoid need for attachment operator. From 63d7fbf55cc024347d30f676e554fdfd29907aa7 Mon Sep 17 00:00:00 2001 From: Henrik Tidefelt Date: Wed, 30 Nov 2022 13:42:11 +0100 Subject: [PATCH 06/11] Make room for top level package annotation Needed for the SourceLocation-annotation. --- RationaleMCP/0031/grammar.md | 1 + 1 file changed, 1 insertion(+) diff --git a/RationaleMCP/0031/grammar.md b/RationaleMCP/0031/grammar.md index d1e4b5b43..b3ca70ac5 100644 --- a/RationaleMCP/0031/grammar.md +++ b/RationaleMCP/0031/grammar.md @@ -70,6 +70,7 @@ The _S-CHAR_ accepts Unicode other than " and \\: >    | _global-constant_ **;**\ >    )*\ >    **model** _long-class-specifier_ **;**\ +>    ( _annotation-comment_ **;** )? >   **end** _IDENT_ **;** Here, the _VERSION-HEADER_ is a Flat Modelica variant of the not yet standardized language version header for Modelica proposed in [MCP-0015](https://github.com/modelica/ModelicaSpecification/tree/MCP/0015/RationaleMCP/0015): From c664d40486379287d92bf1ee161407e07af1655f Mon Sep 17 00:00:00 2001 From: Henrik Tidefelt Date: Wed, 14 Dec 2022 15:10:36 +0100 Subject: [PATCH 07/11] Conclusion regarding which information to include in decorations According to today's web meeting decision. --- RationaleMCP/0031/source-locations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/RationaleMCP/0031/source-locations.md b/RationaleMCP/0031/source-locations.md index b34289a17..f726147cf 100644 --- a/RationaleMCP/0031/source-locations.md +++ b/RationaleMCP/0031/source-locations.md @@ -68,7 +68,7 @@ The alternatives above could also be combined in different ways: ### Conclusion -None yet, but all discussion so far has pointed in the direction of just a single integer. +For now, only allow a single integer. It would be easy to extend this in future versions of Flat Modelica. ## Syntax for source location decoration attachment From 7478d1bf7be24fd51f0d796a9a8652deb57e6550 Mon Sep 17 00:00:00 2001 From: Henrik Tidefelt Date: Thu, 16 Feb 2023 10:37:46 +0100 Subject: [PATCH 08/11] Fix typo --- RationaleMCP/0031/source-locations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/RationaleMCP/0031/source-locations.md b/RationaleMCP/0031/source-locations.md index f726147cf..52350b14e 100644 --- a/RationaleMCP/0031/source-locations.md +++ b/RationaleMCP/0031/source-locations.md @@ -94,7 +94,7 @@ annotation(SourceLocations(…)); end 'MyModel'; ``` -The precedence of `@` is lower than the expression operators, so that no parentheses are needed when attaching a source locaiton to a modification or binding. +The precedence of `@` is lower than the expression operators, so that no parentheses are needed when attaching a source location to a modification or binding. #### Low precedence infix `!` operator From 743d0c7587cf48b275f704fcf3c751caf97517ae Mon Sep 17 00:00:00 2001 From: Henrik Tidefelt Date: Wed, 22 Feb 2023 23:19:51 +0100 Subject: [PATCH 09/11] Extend grammar with source location decorations --- RationaleMCP/0031/grammar.md | 28 +++++++++++++++++----------- 1 file changed, 17 insertions(+), 11 deletions(-) diff --git a/RationaleMCP/0031/grammar.md b/RationaleMCP/0031/grammar.md index b3ca70ac5..56c4d2bfb 100644 --- a/RationaleMCP/0031/grammar.md +++ b/RationaleMCP/0031/grammar.md @@ -66,10 +66,10 @@ The _S-CHAR_ accepts Unicode other than " and \\: > _flat-modelica_ →\ >   _VERSION-HEADER_\ >   **package** _IDENT_\ ->    ( _class-definition_ **;**\ ->    | _global-constant_ **;**\ +>    ( _decoration_? _class-definition_ **;**\ +>    | _decoration_? _global-constant_ **;**\ >    )*\ ->    **model** _long-class-specifier_ **;**\ +>    _decoration_? **model** _long-class-specifier_ **;**\ >    ( _annotation-comment_ **;** )? >   **end** _IDENT_ **;** @@ -130,14 +130,14 @@ end _F; > _enumeration-literal_ → _IDENT_ _comment_ > _composition_ →\ ->   (_generic-element_ **;**)* \ +>   (_decoration_? _generic-element_ **;**)* \ >   ( **equation** ( _equation_ **;** )* \ >   | **initial** **equation** ( _initial-equation_ **;** )* \ >   | **initial**? **algorithm** ( _statement_ **;** )* \ >   ~~| **public** (_generic-element_ **;**)*~~ \ >   ~~| **protected** (_generic-element_ **;**)*~~ \ >   )* \ ->   ( **external** _language-specification_?\ +>   ( _decoration_? **external** _language-specification_?\ >    _external-function-call_? _annotation-comment_? **;**\ >   )?\ >   _base-partition_* \ @@ -190,7 +190,7 @@ end _F; >   | **algorithm** ( _statement_ **;** )* \ >   )* -> _clock-clause_ → **Clock** _IDENT_ **=** _expression_ _comment_ +> _clock-clause_ → _decoration_? **Clock** _IDENT_ **=** _expression_ _comment_ ## B23 Extends @@ -231,7 +231,7 @@ end _F; > _argument-list_ → _argument_ ( **,** _argument_ )* > _argument_\ ->   → _element-modification-or-replaceable_\ +>   → _decoration_? _element-modification-or-replaceable_\ >   ~~| _element-redeclaration_~~ > _element-modification-or-replaceable_ →\ @@ -266,7 +266,8 @@ end _F; ## B26 Equations > _equation_ →\ ->   ( _simple-expression_ ( **=** _expression_ )?\ +>   _decoration_?\ +>   ( _simple-expression_ _decoration_? ( **=** _expression_ )?\ >   | _if-equation_\ >   | _for-equation_\ >   ~~| _connect-clause_~~\ @@ -277,6 +278,7 @@ end _F; > _initial-equation_ → _equation_ | _prioritize-equation_ > _statement_ →\ +>   _decoration_?\ >   ( _component-reference_ ( **:=** _expression_ | _function-call-args_ )\ >   | `[(]` _output-expression-list_ `[)]` **:=** _component-reference_ _function-call-args_\ >   | **break**\ @@ -356,12 +358,16 @@ end _F; ## Expressions -> _expression_ → _simple-expression_ | _if-expression_ +> _decoration_ → **@** UNSIGNED-INTEGER + +> _expression_ → _expression-no-decoration_ _decoration_? + +> _expression-no-decoration_ → _simple-expression_ | _if-expression_ > _if-expression_ →\ >   **if** _expression_ **then** _expression_\ >   ( **elseif** _expression_ **then** _expression_ )* \ ->   **else** _expression_ +>   **else** _expression-no-decoration_ > _simple-expression_ → _logical-expression_ ( **:** _logical-expression_ ( **:** _logical-expression_ )? )? @@ -392,7 +398,7 @@ end _F; >   | **true**\ >   | ( **der** | **initial** | **pure** ) _function-call-args_\ >   | _component-reference_ _function-call-args_?\ ->   | `[(]` _output-expression-list_ `[)]` _array-subscripts_?\ +>   | `[(]` _decoration_? _output-expression-list_ `[)]` _array-subscripts_?\ >   | `[[]` _expression-list_ ( **;** _expression-list_ )* `[]]`\ >   | **{** _array-arguments_ **}**\ >   | **end** From 9d3b84cec027fd02927da9bb18923626040d6b71 Mon Sep 17 00:00:00 2001 From: Henrik Tidefelt Date: Tue, 4 Apr 2023 11:27:25 +0200 Subject: [PATCH 10/11] Remove 'decoration?' in prefix position inside parenthesis --- RationaleMCP/0031/grammar.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/RationaleMCP/0031/grammar.md b/RationaleMCP/0031/grammar.md index 56c4d2bfb..daa608b4e 100644 --- a/RationaleMCP/0031/grammar.md +++ b/RationaleMCP/0031/grammar.md @@ -398,7 +398,7 @@ end _F; >   | **true**\ >   | ( **der** | **initial** | **pure** ) _function-call-args_\ >   | _component-reference_ _function-call-args_?\ ->   | `[(]` _decoration_? _output-expression-list_ `[)]` _array-subscripts_?\ +>   | `[(]` _output-expression-list_ `[)]` _array-subscripts_?\ >   | `[[]` _expression-list_ ( **;** _expression-list_ )* `[]]`\ >   | **{** _array-arguments_ **}**\ >   | **end** From 415d4b58f8612a0a5b8cedc88dde171cd5690b10 Mon Sep 17 00:00:00 2001 From: Henrik Tidefelt Date: Tue, 18 Apr 2023 12:14:59 +0200 Subject: [PATCH 11/11] Use expression-no-decoration everywhere in if-expression --- RationaleMCP/0031/grammar.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/RationaleMCP/0031/grammar.md b/RationaleMCP/0031/grammar.md index daa608b4e..49df02138 100644 --- a/RationaleMCP/0031/grammar.md +++ b/RationaleMCP/0031/grammar.md @@ -365,8 +365,8 @@ end _F; > _expression-no-decoration_ → _simple-expression_ | _if-expression_ > _if-expression_ →\ ->   **if** _expression_ **then** _expression_\ ->   ( **elseif** _expression_ **then** _expression_ )* \ +>   **if** _expression-no-decoration_ **then** _expression-no-decoration_\ +>   ( **elseif** _expression-no-decoration_ **then** _expression-no-decoration_ )* \ >   **else** _expression-no-decoration_ > _simple-expression_ → _logical-expression_ ( **:** _logical-expression_ ( **:** _logical-expression_ )? )?