Markup and DSL

Markup and DSL Pub Share

The specifications and stories (as well as every page you see here) are simple wiki topics, created using markdown, which is much, much simpler and friendly than good old HTML. In your own projects, you'll see the "edit" option activated at the bottom of each topic or page.

In markdown, for instance, you type **bold** to get bold and * list member to get

list member

... and so on. Read more on Modified markdown syntax here, to read on the extensions we added to simple markdown and the special syntax to include photos, videos, properties etc. Also, see more detaiils in Wiki Properties.

DSL and active content

We expanded on the idea of markdown, to allow you to insert active content in the markdown text, so, inside any topic, special syntax can be used to... uhh... create active content which makes the domain engine do certain interesting things.

So, while in a regular programming language you would focus on the code and comments would be a secondary concern, marked up with special delimitators like //:

// a function example in javascript

// handling the message event
function on_a_message () {
  console.echo ("saying hello..."); // print to console
  return "hello";

While, in diesel, we think that the story and documentation is as valuable as the code itself, so the text and the rules are equal, marked up by keyworkds like $mock or $class:

In here, text rules and code is marked up.

Mocking the handling the special `a.message`:

$mock a.message 
=> ctx.echo(msg="saying hello...") // print in trace
=> (payload="hello")

For instance, to create a mock of a message, a single line with this directive:

$mock a.message => (payload="hello")

would instruct the engine to mock a message called a.message and return "hello" when that message shows up somehow and needs processing.

Note that regular block syntax is useful for larger logic blocks:

$mock a.message {
  ctx.echo(msg="saying hello...") // print in trace
  if (weLikeHim) {
    (payload="hello")
  } else {
    (payload = "'sup")
  }
}

The one thing to understand syntax-wise is the escape sequence, using the backtick character (similar to defining a <pre></pre> block). A single backtick for inline text and a triple backtick for escaping a multi-line block. Any text you escape with the back-ticks, will not be interpreted as an "instruction" but just be displayed like it is, in a pre tag, like this one:

$mock a.message 
=> ctx.echo(msg="saying hello...")
=> (payload="hello")

...and here it is not escaped (so the following lines just defined a rule, not just show you how to do it):

0 $mock:: test.mdsl.message
ctx.echo (msg="saying hello..."="saying he...)
. (payload="hello")

As you can see, the second version looks different from the text creating it - this means that the engine understands this construct and... right now, this page contains a mock - if you sent this page the a.message message, say by clicking on this link, you'd get "hello" back.

Long story short is that the engine understood there's a rule here, automatically created a REST service and when you clicked the link, it will execute the mocking rule above. You can jump ahead and read more about the REST bindings at Snakking REST, rest spec⁺⁺ and rest story⁺⁺ as well as REST and HTTP templates.

Stories | requirements

So there you have it. You can create new stories (plain wiki topics), focusing on the actual requirements and user stories and sprinkle some DSL syntax here and there to create "active" elements.

For instance, here is a test for the mock rule above - this will "send" the message and then check that we got the expected payload back:

$send test.mdsl.message 
$expect (payload is "hello")

You can create a small, large or even huge set of stories, linked and interconnected into a coherent domain and the engine will recognize the "active elements" and act on them.

Specs | rules

While you can mix and match the mocks and rules with testing and expectations, like we did here, you would normally separate the tests into "stories" and the specifications / definintions, into "specs".

Here you can implement the rule we mocked above:

$send test.mdsl.message 
$expect (payload is "hello")

Domain | domain modelling

As far as domain modelling goes, you can define classes with attributes and associations, here's some of the stuff you can do (annottions, types, references, use expressions etc):

Define a class:
$anno (table="TestClass1")
$anno (inventory="diesel.db.memshared")
$class TestClass1 [T] (
  someValue:String, 
  ref:<>TestClass2,
  @key name, 
  @excache timestamp
  )
  
$class Class1 (name, timestamp = now())
$val c = new Class1 {name="jake"}