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
... 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.
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
While, in diesel, the text is the main concern and the "code" secondary, marked up by keyworkds like
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):
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.
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
$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.
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.