Add support for structured model annotations

sybila / biodivine-lib-param-bn

Rust library for working with parametrised Boolean networks.

MIT License

2 stars 3 forks source link

In this pull request, we add "structured model annotations". These are comments that can be added to any .aeon file and parsed into a well-defined data structure. As such, they are useful when implementing machine-readable metadata or providing other model-related information that isn't an immediate part of the model (see examples below).

Annotation syntax:

#! (path_segment:)* annotation_value

For example, here is a simple list of annotations which describe the model and its variables:

#! name: My fancy model
#! description: Description of my fancy model.
#! description: Also part of the model description.
#! description : variable : var_x : First variable.
#! description : variable : var_y : Second variable.

Overall, the annotations are parsed into a tree. The levels of the tree are the path segments. If a specific "tree node" appears multiple times, the contents of the annotation are concatenated as multiple lines. In this case, the root has two children: name and description. Node name has only a text value ("My fancy model"), while description has both a two-line value, and a child variable which contains the remaining sub-tree.

We can access annotations using path selectors. For example, after parsing this input into a variable annotations, we can run annotations.get_value(&["description", "variable", "var_x"]) to obtain the value "First variable". More about the API is available in the tutorial page which is part of the pull request.

Escaping

Normally, path segments should only contain alphanumeric characters and underscores. However, they can be escaped using a back-tick (`). Consequently, a back-tick cannot appear in any path segment. Similarly, colons cannot appear in annotation values. However, an annotation value VAL can be escaped with ` #VAL# `. Such escaping can be also used to preserve surrounding white-space, as the parser normally removes it.

Other examples

A simple "model layout" can be easily included in this way:

#! layout : var_x : 144,152
#! layout: var_y : 13,56
...

A list of properties of a BN sketch can be given using annotations:

#! static_property: #`forall{x}: f(x, 1) > f(x, 0)`#
#! dynamic_property: #`exists{x}: at{x}: AX {x}`#

Codecov Report

Base: 76.90% // Head: 77.27% // Increases project coverage by +0.37% :tada:

Coverage data is based on head (025050c) compared to base (e0d0377). Patch coverage: 88.09% of modified lines in pull request are covered.

Additional details and impacted files

```diff @@ Coverage Diff @@ ## master #40 +/- ## ========================================== + Coverage 76.90% 77.27% +0.37% ========================================== Files 72 76 +4 Lines 4113 4238 +125 ========================================== + Hits 3163 3275 +112 - Misses 950 963 +13 ``` | [Impacted Files](https://codecov.io/gh/sybila/biodivine-lib-param-bn/pull/40?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=sybila) | Coverage Δ | | |---|---|---| | [src/lib.rs](https://codecov.io/gh/sybila/biodivine-lib-param-bn/pull/40?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=sybila#diff-c3JjL2xpYi5ycw==) | `60.00% <ø> (+26.66%)` | :arrow_up: | | [src/\_impl\_annotations/\_impl\_annotation.rs](https://codecov.io/gh/sybila/biodivine-lib-param-bn/pull/40?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=sybila#diff-c3JjL19pbXBsX2Fubm90YXRpb25zL19pbXBsX2Fubm90YXRpb24ucnM=) | `78.33% <78.33%> (ø)` | | | [src/\_impl\_annotations/\_impl\_writer.rs](https://codecov.io/gh/sybila/biodivine-lib-param-bn/pull/40?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=sybila#diff-c3JjL19pbXBsX2Fubm90YXRpb25zL19pbXBsX3dyaXRlci5ycw==) | `94.59% <94.59%> (ø)` | | | [src/\_impl\_annotations/\_impl\_reader.rs](https://codecov.io/gh/sybila/biodivine-lib-param-bn/pull/40?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=sybila#diff-c3JjL19pbXBsX2Fubm90YXRpb25zL19pbXBsX3JlYWRlci5ycw==) | `100.00% <100.00%> (ø)` | | | [src/\_impl\_annotations/mod.rs](https://codecov.io/gh/sybila/biodivine-lib-param-bn/pull/40?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=sybila#diff-c3JjL19pbXBsX2Fubm90YXRpb25zL21vZC5ycw==) | `100.00% <100.00%> (ø)` | | Help us with your feedback. Take ten seconds to tell us [how you rate us](https://about.codecov.io/nps?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=sybila). Have a feature suggestion? [Share it here.](https://app.codecov.io/gh/feedback/?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=sybila)

sybila / biodivine-lib-param-bn