Markup and DSL Pub   Share

The 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 "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, the text is the main concern and the "code" secondary, marked up by keyworkds like $mock:

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.

The one thing to understand syntax-wise is the escape sequence, using the backtick character. 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. You can also create a sequence, here it is escaped:

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

...and here it is not escaped (how it looks like in the page):

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.

Note that the engine automatically created a REST service and when invoked, 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

So there you have it. You can create new stories (plain wiki topics), focusing on the actual story 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

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".

Next: Requirements and stories.

You need to log in to post a comment!