Skip to content
Snippets Groups Projects
Commit b71daace authored by René Schöne's avatar René Schöne
Browse files

Resolve "Refactorings/Clean-Up"

- add cloc and two use cases to pages
- move some aspects into separate template files
- add a method to reset the evaluation counter
- rename forwardingNTA to forwarding
- begin with default mappings using templates 
- also indirectly work on #55 to include marshalling methods only when needed
- move TestUtils to a separate package
parent da232e01
Branches
No related tags found
3 merge requests!39Version 1.1.0,!35Version 1.0.0,!33Resolve "Refactorings/Clean-Up"
Showing
with 171 additions and 36 deletions
......@@ -100,12 +100,25 @@ ragdoc_view:
paths:
- "pages/docs/ragdoc"
build_cloc:
image: "alpine:latest"
needs:
- build
script:
- apk add cloc
- cd pages/cloc
- sh run-cloc.sh
artifacts:
paths:
- pages/docs/cloc.md
.pages-template:
image: python:3.10.0-bullseye
stage: publish
needs:
- ragdoc_view
- test
- build_cloc
before_script:
- pip install -r pages/requirements.txt
script:
......@@ -117,7 +130,7 @@ pages-dry-run:
- dev
- master
pages-master:
pages:
extends: .pages-template
artifacts:
paths:
......
......@@ -4,3 +4,11 @@ plugins {
}
java.toolchain.languageVersion.set(JavaLanguageVersion.of(11))
if (JavaVersion.current().isJava8Compatible()) {
allprojects {
tasks.withType(Javadoc) {
options.addStringOption('Xdoclint:none', '-quiet')
}
}
}
log4j_version = 2.17.2
mustache_java_version = 0.9.10
preprocessor_version = 0.1.0-41
relast_version = 0.3.0-137
dumpAst_version = 1.2.0
/docs/ragdoc/
/docs/cloc.md
__pycache__
run-cloc.sh
files.csv
my_definitions.txt
ragconnect.base.lang
ragconnect.file
ragconnect.lang
ragconnect.base-*.md
ragconnect.base-*.txt
ragconnect.tests-*.md
ragconnect.tests-*.txt
tmp.json
Connect
filter call_regexp_common Java
extension connect
extension ragconnect
3rd_gen_scale 10
Flex
filter remove_matches ^\s*//
extension flex
3rd_gen_scale 1.5
Grammar
filter call_regexp_common Java
extension ast
extension relast
3rd_gen_scale 30
Attributes
filter call_regexp_common Java
extension jrag
extension jadd
3rd_gen_scale 1.5
Parser
filter remove_matches ^\s*//
extension parser
3rd_gen_scale 1.5
#!/bin/bash
if [ "$1" == "-h" ] || [ "$1" == "--help" ]; then
echo "-s -> skip running cloc commands"
echo "-a -> produce files.csv with code count for single src files"
exit
fi
if [ "$1" != "-s" ]; then
# --force-lang=Java,jrag --force-lang=Java,jadd
DEF_FILE=my_definitions.txt
echo "Export language definitions"
cloc --quiet --write-lang-def="$DEF_FILE"
for f in cloc-def-*.txt;
do
cat $f >> "$DEF_FILE"
done
REPO_ROOT="../.."
CLOC_CMD="cloc --exclude-lang=JSON --read-lang-def=my_definitions.txt --exclude-list-file=.clocignore --quiet --hide-rate"
# --ignored=bad-files.txt
cloc_double() {
f=$1
shift
echo "Creating $f.txt"
$CLOC_CMD --report-file="$f.txt" $@
echo "Creating $f.md"
$CLOC_CMD --md --report-file=tmp.md $@
tail -n+3 tmp.md > "$f.md"
rm tmp.md
}
make_page() {
echo "# Evaluation Metrics: Lines of Code"
echo
echo "## Manually written generator code"
echo
cat ragconnect.base-src-result.md
echo
echo "## Generated generator code"
cat ragconnect.base-gen-result.md
echo
echo "## Manually written test code"
cat ragconnect.tests-src-result.md
echo
echo "## Generated test code"
cat ragconnect.tests-gen-result.md
}
fi
if [ "$1" != "-s" ] && [ "$1" != "-a" ]; then
echo "Running cloc with new definitions"
cloc_double "ragconnect.base-src-result" --found=ragconnect.base-src-found.txt ${REPO_ROOT}/ragconnect.base/src/main/
cloc_double "ragconnect.base-gen-result" --found=ragconnect.base-gen-found.txt ${REPO_ROOT}/ragconnect.base/src/gen/jastadd ${REPO_ROOT}/ragconnect.base/src/gen/java
cloc_double "ragconnect.tests-src-result" --found=ragconnect.tests-src-found.txt ${REPO_ROOT}/ragconnect.tests/src/test/01-input/ ${REPO_ROOT}/ragconnect.tests/src/test/java/
cloc_double "ragconnect.tests-gen-result" --found=ragconnect.tests-gen-found.txt ${REPO_ROOT}/ragconnect.tests/src/test/02-after-ragconnect/ ${REPO_ROOT}/ragconnect.tests/src/test/java-gen
$CLOC_CMD --sum-reports --report_file=ragconnect ragconnect.base-src-result.txt ragconnect.base-gen-result.txt ragconnect.tests-src-result.txt ragconnect.tests-gen-result.txt
echo "Creating ../docs/cloc.md"
make_page > ../docs/cloc.md
fi
if [ "$1" == "-a" ]; then
echo "filename,code" > files.csv
for f in $(find ${REPO_ROOT}/ragconnect.base/src/main/ ${REPO_ROOT}/ragconnect.base/src/gen/jastadd-sources/ -type f); do
printf '.'
echo $f,$($CLOC_CMD --json $f | jq '.SUM.code') >> files.csv
done
echo
exit
fi
# cat ragconnect.base-src-result.txt
# cat ragconnect.base.file
# cat ragconnect.tests-result.txt
echo "LOC stats:"
echo "Language files blank comment code"
( for t in *-result.txt ; do echo -e "==> $t <=="; grep -v -e '---' -e 'SUM' -e 'Language' -e 'github' $t; done)
echo
echo "Summary:"
grep -v -e '---' -e 'SUM' -e 'Language' -e 'github' ragconnect.file
......@@ -4,9 +4,9 @@
### Changes
- Allow connection endpoints for relations ([#37](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/37)) and attributes ([#38](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/38))
- Allow send connection endpoints non-NTA nonterminals ([#36](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/36))
- Allow context-free context endpoints ([#34](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/34))
- Allow connection ports for relations ([#37](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/37)) and attributes ([#38](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/38))
- Allow send connection ports non-NTA nonterminals ([#36](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/36))
- Allow context-free context ports ([#34](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/34))
- Experimental support for Java handler ([#52](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/52))
- Make specification language more concise ([#33](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/33))
......@@ -17,24 +17,24 @@
## 0.3.2
- Allow connection endpoints for list nonterminals ([#21](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/21))
- Allow connection ports for list nonterminals ([#21](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/21))
- Ensure correct connect and disconnect functionality ([#31](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/31))
- Enhance documentation ([#13](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/13), [#20](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/20), [#41](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/41))
## 0.3.1
- Full support for incremental dependency tracking
- Full support for subtree endpoint definitions ([#9](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/9))
- Full support for subtree port definitions ([#9](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/9))
- Internal: Use updated gradle plugin for tests ([#18](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/18))
- Bugfix [#22](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/22): Correct handling of malformed URIs passed when connecting an endpoint
- Bugfix [#23](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/23): Correct handling of OptComponents as endpoints
- Bugfix [#22](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/22): Correct handling of malformed URIs passed when connecting an port
- Bugfix [#23](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/23): Correct handling of OptComponents as ports
- Bugfix [#27](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/27): Correctly handle whitespaces in grammars
## 0.3.0
- Added [API documentation](ragdoc/index.html) to documentation
- Add methods to `disconnect` an endpoint
- Internal: PoC for incremental dependency tracking and subtree endpoint definitions ([#14](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/14))
- Add methods to `disconnect` a port
- Internal: PoC for incremental dependency tracking and subtree port definitions ([#14](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/14))
- Bugfix [#17](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/17): Added missing support for `boolean`
## 0.2.2
......
......@@ -90,9 +90,9 @@ However, depending on the selected protocols and/or used features, additional de
- JastAdd version has to support `INC_FLUSH_START` and `INC_FLUSH_END` (i.e., has [issue #329][jastadd-issue-329] resolved)
- [Feature description](using.md#dependency-tracking-automatically-derived)
### Tree/List Endpoints
### Tree/List Ports
- Condition: When using endpoints along with default mappings for subtrees
- Condition: When using ports along with default mappings for subtrees
- Required runtime dependencies:
- `group: 'com.fasterxml.jackson.core', name: 'jackson-core', version: '2.12.1'`
- `group: 'com.fasterxml.jackson.core', name: 'jackson-databind', version: '2.12.1'`
......
......@@ -3,14 +3,14 @@
# The RagConnect Specification Language
To declare endpoints and mappings, a domain-specific language ([DSL](https://en.wikipedia.org/wiki/Domain-specific_language)) is used.
To declare ports and mappings, a domain-specific language ([DSL](https://en.wikipedia.org/wiki/Domain-specific_language)) is used.
## Endpoints
## Ports
An endpoint marks an element of an AST as sending or receiving element.
The kind of the element determines, whether an endpoint for it can be receiving, sending, or both at the same time.
A port marks an element of an AST as sending or receiving element.
The kind of the element determines, whether an port for it can be receiving, sending, or both at the same time.
To declare a new endpoints, use the following syntax:
To declare a new ports, use the following syntax:
```
("send"|"receive") ["indexed"] ["with add"] <Non-Terminal>[.<Target>["(<AttributeType>)"]] ["using" <Mapping-Name> (, <Mapping-Name>)*] ";"
......@@ -18,34 +18,34 @@ To declare a new endpoints, use the following syntax:
A breakdown of the parts of that syntax:
- The first word (`send` or `receive`) defines the kind of endpoint - sending or receiving, respectively.
- The optional `indexed` applies only for list children and lets the endpoint act on elements of that list.
This only works for receiving endpoints, and is further changed by `with add`.
- The first word (`send` or `receive`) defines the kind of port - sending or receiving, respectively.
- The optional `indexed` applies only for list children and lets the port act on elements of that list.
This only works for receiving ports, and is further changed by `with add`.
- A lonely `indexed` assigns each incoming "topic" to an index in a list.
This can be useful if multiple instances of this endpoint are connected, or the communication protocol supports wildcard topics.
This can be useful if multiple instances of this port are connected, or the communication protocol supports wildcard topics.
For the former case, the connect method with an explicit index can be used, whereas the "normal" connect method without the index acts as a method for "wildcard-connect".
- Combining `indexed with add`, incoming data is required to be an element of the list, and will be appended to the list.
- The second optional keyword `with add` can also be used only for receiving endpoints targeting a list children.
- The second optional keyword `with add` can also be used only for receiving ports targeting a list children.
As described above, it can be combined with `indexed`.
If used on its own, the incoming data is interpreted as a complete list and its elements will be appended to the current list.
- The `<Non-Terminal>[.<Target>["(<AttributeType>)"]]` notation describes the actual affected node.
- If the target is omitted, all nodes of that non-terminal type can be connected, irrespective of their context. This is a context-free endpoint definition.
- If the target is omitted, all nodes of that non-terminal type can be connected, irrespective of their context. This is a context-free port definition.
- The target can be any child on the right-hand side of a production rule, a role of a relation, or an attribute.
The brackets `(<AttributeType>)` after the target must be used in case of an attribute, and only then.
Here, the return type of the attribute has to be specified, as aspect files are not parsed by RagConnect.
Hence, RagConnect can not and will not verify the existence of the attribute, and the possible non-existence of an attribute will be found by the Java compiler.
- Optionally, an endpoint can use one or more [mappings](#mappings).
- Optionally, a port can use one or more [mappings](#mappings).
They will be applied before sending, or after receiving a message.
Mappings will always be applied in the order they are listed after `using`.
### Context-Free Endpoints
### Context-Free Ports
An endpoint with only a non-terminal and without a target is called context-free endpoint.
Specifying such an endpoint has several consequences:
A port with only a non-terminal and without a target is called context-free port.
Specifying such a port has several consequences:
- The given non-terminal can be connected to in all contexts it occurs as if there were endpoints for all those contexts.
- The given non-terminal can be connected to in all contexts it occurs as if there were ports for all those contexts.
- There is a special method available on the given non-terminal to connect itself, which selects the correct connect-method depending on its context.
- Context-sensitive endpoints for this non-terminal can still be specified to modify mappings in this context. If the context is a list, the endpoint must use `indexed` and cannot use `with add`.
- Context-sensitive ports for this non-terminal can still be specified to modify mappings in this context. If the context is a list, the port must use `indexed` and cannot use `with add`.
**Example**:
......@@ -56,7 +56,7 @@ A ::= <Value> ;
// connect
receive A;
receive Root.SingleA using MyMapping; // specialized endpoint
receive Root.SingleA using MyMapping; // specialized port
```
Implied, additional connect specifications:
......@@ -79,8 +79,8 @@ root.connectOptA("<some-uri-to-connect>");
## Mappings
A mapping is a side effect-free function with one argument (the value that will be transformed) and one result (the transformed value), that will be applied on a value to be sent for a sending endpoint, a received value for a receiving endpoint, or the result of another mapping.
Mappings can be shared between endpoints.
A mapping is a side effect-free function with one argument (the value that will be transformed) and one result (the transformed value), that will be applied on a value to be sent for a sending port, a received value for a receiving port, or the result of another mapping.
Mappings can be shared between ports.
To declare a mapping, use the following syntax:
......@@ -93,16 +93,16 @@ To declare a mapping, use the following syntax:
A breakdown of the parts of that syntax:
- The `<Mapping-Name>` identifies the mapping.
- The `<From-Type` is the type of the input. The type of the first mapping of a receiving endpoint must be `byte[]`.
- The `<From-Type` is the type of the input. The type of the first mapping of a receiving port must be `byte[]`.
- To refer to the input, `<Input-Variable-Name>` defines the name of it.
- The `<To-Type>` is the type of the result. The type of the last mapping of a sending endpoint must be `byte[]`.
- The `<To-Type>` is the type of the result. The type of the last mapping of a sending port must be `byte[]`.
- Finally, the `<Java-Block>` is the actual definition of the mapping using normal Java syntax.
The previously defined input variable can be used via its name here.
This block can contain multiple statements, but must end with a `return` statement.
The validity of this block is not verified by RagConnect itself, but later in the compilation process by the Java compiler.
Note: There are default mappings provided for all primitive Java types (using their "normal" byte representation), and for all non-terminal types (using their JSON representation converted from/to bytes).
Those default mappings apply to both sending and receiving endpoints, and match their counterparts, e.g., the mapping from `int` to `byte[]` uses the same byte representation as the mapping back from `byte[]` to `int`.
Those default mappings apply to both sending and receiving ports, and match their counterparts, e.g., the mapping from `int` to `byte[]` uses the same byte representation as the mapping back from `byte[]` to `int`.
Default mappings are always inserted if either no mapping is present, or if the type of the first/last mapping is not `byte[]` as stated above.
Their main intent is to allow quick prototyping without constraining a more complex use case.
......@@ -112,7 +112,7 @@ Their main intent is to allow quick prototyping without constraining a more comp
Deprecated since `1.0.0`
A dependency definition describes a possible dependency on type-level from a token to an attribute.
Whenever the token changes, the attribute is eagerly re-computed and endpoints attached to it are triggered.
Whenever the token changes, the attribute is eagerly re-computed and ports attached to it are triggered.
Such a dependency must be added on instance-level for every token that could have an influence to the attribute.
An alternative for those explicit dependency definitions is [incremental dependency tracking](using.md#dependency-tracking-automatically-derived).
......
File moved
File moved
pages/docs/img/2022_models/photo.jpg

880 KiB

pages/docs/img/ragconnect-process.png

105 KiB

0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment