This is part one in a series on the 0.3 version of the language spec for the Merg-E Domain Specific Language for the InnuenDo Web 3.0 stack. I'll add more parts to the below list as the spec progresses:
In this short blog post in this series I want to look at the least important language feature from a functionality point of view, but a very important language feature for maintainable code: code comments.
Let's start with a bit of undocumented Merg-E code
#!/usr/bin/env merg-e
app myApp lang resource ambient {
use ambient {
io.cout as cout;
io.cerr as cerr;
io.endl as endl;
};
mutable main ()::{
cout;
cerr;
endl;
}{
inert whole16 max_prime = 1000;
shared mutable whole16 ok_count = 0;
mutable blocker all_primes;
reentrant mutable merge utils.is_prime as is_prime(x whole16)::{
ok_count;
}{
max_prime;
}@[range_error];
take 100 {
all_primes += is_prime(current + 1 nopromote);
};
await_all all_primes;
cout "counted " ok_count " prime numbers" endl;
}!!{
range_error : {
cerr "Something went wrong" endl;
}};
};
Because Merg-E is supposed to be a Web 3.0 DSL and because markdown is an important format in Web 3.0 chains like HIVE, we are intoducing the concept of reversed-markdown for documentation.
In markdown, if you want to include a bit of code, you need to start with three backtics ``` , optionaly a language name , then a newline, your code, another newline, and then three backticks again.
# My document
Some text here
```python
#!/usr/bin/env python
print("Helo world")
```
In code it is unlikely that you will want to quote other code, so how about we just reverse it. We use the three backticks to denote markdown documentation embedded in our code
#!/usr/bin/env merg-e
```userdoc
# myApp
This is a silly App to demonstrate some basic Merg-E syntax.
The App counts how many prime numbers there are between 1 and 100.
```
app myApp lang resource ambient {
...
};
Note how we use userdoc as pseudo language name. We distinguish documentation at three levels.
It is recomended to keep impldoc to a bare minimum and only use it for non intuitive code or non-intuitive concurency constructs.
Documentation blocks dont need to strictly follow Ratliff style indentation, but the tripple backtics does. Next to that, up to the indentation of the tripple backtics, leading spaces are considered to need to be removed in order to try to make valid markdown.
#!/usr/bin/env merg-e
```userdoc
## myApp
This is a silly App to demonstrate some basic Merg-E syntax.
The App counts how many prime numbers there are between 1 and 100.
```
app myApp lang resource ambient {
```devdoc
### imports
Import the ambient authority needed for outputing text to the user.
```
use ambient {
io.cout as cout;
io.cerr as cerr;
io.endl as endl;
};
mutable main ()::{
cout;
cerr;
endl;
}{
inert whole16 max_prime = 1000;
shared mutable whole16 ok_count = 0;
mutable blocker all_primes;
```impldoc
#### range errors on is_prime
Please note that is_prime will throw a range_error when given an integer smaller than 1 or larger than max_prime
```
reentrant mutable merge utils.is_prime as is_prime(x whole16)::{
ok_count;
}{
max_prime;
}@[range_error];
take 100 {
all_primes += is_prime(current + 1 nopromote);
};
await_all all_primes;
cout "counted " ok_count " prime numbers" endl;
}!!{
range_error : {
cerr "Something went wrong" endl;
}};
};
So what is so great about reverse markdown? Well, we can make a simple markdown reverser in just a few dozen lines of code. All it needs to do is de-indent inside of the comment blocks and move around som,e backtics. Let's see what a reversed markdown of the previous code looks like:
## myApp
This is a silly App to demonstrate some basic Merg-E syntax.
The App counts how many prime numbers there are between 1 and 100.
```merg-e
app myApp lang resource ambient {
...
```
### imports
Import the ambient authority needed for outputing text to the user.
```merg-e
use ambient {
io.cout as cout;
io.cerr as cerr;
io.endl as endl;
};
mutable main ()::{
cout;
cerr;
endl}{
inert whole16 max_prime = 1000;
shared mutable whole16 ok_count = 0;
mutable blocker all_primes;
```
#### range errors on is_prime
Please note that is_prime will throw a range_error when given an integer smaller than 1 or larger than max_prime
```merg-e
reentrant mutable merge utils.is_prime as is_prime(x whole16)::{
ok_count;
}{
max_prime;
}@[range_error];
take 100 {
all_primes += is_prime(current + 1 nopromote);
};
await_all all_primes;
cout "counted " ok_count " prime numbers" endl;
}!!{
range_error : {
cerr "Something went wrong" endl;
}};
};
```
Right now all three levels are there, but the idea is to allow the tool to be able to strip out impldoc or impldoc + devdoc if desired.
To better demonstrate, I'll paste the markdown below to show how a document markdown of this simple script would end up looking:
This is a silly App to demonstrate some basic Merg-E syntax.
The App counts how many prime numbers there are between 1 and 100.
app myApp lang ambient {
...
Import the ambient authority needed for outputing text to the user.
use ambient {
io.cout as cout;
io.cerr as cerr;
io.endl as endl;
};
mutable main ()::{
cout;
cerr;
endl;
}{
inert whole16 max_prime = 1000;
shared mutable whole16 ok_count = 0;
mutable blocker all_primes;
Please note that is_prime will throw a range_error when given an integer smaller than 1 or larger than max_prime
reentrant mutable merge utils.is_prime as is_prime(x whole16)::{
ok_count;
}{
max_prime;
}@[range_error];
take 100 {
all_primes += is_prime(current + 1 nopromote);
};
await_all all_primes;
cout "counted " ok_count " prime numbers" endl;
}!!{
range_error : {
cerr "Something went wrong" endl;
}};
};
In this post I'v addressed the documentation strings in the Merg-E draft language design. I'll need a few more posts to talk about things like freezing, attenuation and decomposition, parallelism models, actors, capability patterns, and a few more. Things are still very fluid on a number of these, and the descriptions in this and the previous post are already different from my first post on the subject ten days ago. Stick around for upcoming posts in this series.